refcount – Atomic Reference Counting C API (User)



Name

refcount_add_load_strong(…) – add and load reference (strong thread-safety)


Synopsis

#include < refcount.h >

refcount_t* refcount_add_load_strong(refcount_t* volatile *psloc, int count);


Description

The refcount_add_load_strong(…) function is used to acquire a reference to a refcount_t from a shared location. This function guarantees that the entire reference acquisition is atomically thread-safe and will strictly adhere to a thread-safety level of strong.

The ‘psloc’ parameter MUST point to a shared location in memory that contains either a pointer to a refcount_t object or NULL. The ‘count’ parameter MUST be a value that is greater than 0. The caller will be subjected to undefined-behavior if the ‘psloc’ or ‘count’ parameters contain values that violate those rules.

If the function successfully acquires a reference then it guarantees that the previous reference count of the acquired reference will have been atomically incremented by ‘count’.

If the function fails, no reference will be acquired from ‘psloc’ and no reference count updates will occur.


Return Value

If successful, the refcount_add_load_strong(…) function returns a pointer to the acquired reference. Otherwise, it will return NULL.


Errors

The refcount_add_load_strong(…) function will fail if:

[NULL] - The shared location pointed to by ‘psloc’ contained NULL.

[Undefined Behavior] - The values of ‘psloc’ or ‘count’ were invalid.