refcount – Atomic Reference Counting C API (User)



Name

refcount_init(…) – initialize a refcount_t object (thread-safety: none)


Synopsis

#include < refcount.h >

int refcount_init(refcount_t *_this, int count, refcount_fpdtor_t fpdtor, void *state);


Description

The refcount_init(…) function is used to initialize a refcount_t object with a initial reference count, a function pointer to a destructor function and a state pointer. The initialization of the refcount object will be not be atomic and will strictly adhere to a thread-safety level of none.

The ‘_this’ parameter MUST point to a refcount_t object that MUST not be acquired by any other thread (e.g., private to the caller) but the caller, only then can it make use of this function. The ‘count’ parameter MUST be a value that is greater than 0. The ‘fpdtor’ parameter MUST point to a valid function that is compatible with the ‘refcount_fpdtor_t’ function pointer type. The ‘state’ parameter MUST not be NULL. The caller will be subjected to undefined-behavior if the ‘_this’, ‘count, ‘fpdtor’ or ‘state’ parameters contain any values that violate those rules.

Return Value

If successful, the refcount_init(…) function returns a non-zero value. Otherwise, it returns 0.


Errors

The refcount_init(…) function will fail if:

[0] – The value of ‘count’ was less than 1.

[Undefined Behavior] - The values of ‘_this’, ‘count, ‘fpdtor’ or ‘state’ are invalid.