refcount – Atomic Reference Counting C API (User)



Name

refcount_sub_strong(…) – subtract reference (strong/basic thread-safety)


Synopsis

#include < refcount.h >

int refcount_sub_strong(refcount_t volatile *sloc, int count);


Description

The refcount_sub_strong(…) function is used to decrement the reference count of a refcount_t object. This function guarantees that the entire reference decrement operation is atomically thread-safe and will strictly adhere to a thread-safety level of strong if the result of the decrement is less than 1 (e.g., it’s atomically thread-safe with all concurrent/parallel increments). Otherwise it adheres to a thread-safety level of basic.

The ‘sloc’ parameter MUST point to NULL or a refcount_t object that MUST be acquired by or transferred to the calling thread before it calls into this function. The ‘count’ parameter MUST be a value that is greater than or equal to 0. The caller will be subjected to undefined-behavior if the ‘sloc’ or ‘count’ parameters contain any values that violate those rules.

The function WILL atomically decrement the reference count of the refcount_t object in ‘sloc’ by ‘count’, if ‘sloc’ is not NULL. If the destructor function pointer will get called if it’s not NULL and if the result of the atomic decrement of the reference count is less than 1. The function can be considered successful in this case.

If ‘sloc’ is not NULL then the function renders the refcount_t object invalid to the calling thread. If the calling thread makes use of the refcount_t in this case, it WILL be subject to undefined behavior.

If the function fails, that means that ‘sloc’ pointed to a location that contained NULL or the result of the decrement was greater than 0.


Return Value

If successful, the refcount_sub_strong(…) function returns a value other than NULL. Otherwise, it will return NULL.


Errors

The refcount_sub_strong(…) function will fail if:

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

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