refc.h File Reference

#include <stdint.h>
#include <stdatomic.h>
#include <stdlib.h>
#include <stdbool.h>

Go to the source code of this file.

Typedefs
typedef unsigned int	refc_type_t
	Use case:

Functions
typedef	_Atomic (refc_type_t) refc_t
	Atomic reference counter type.
refc_type_t	addrefn (refc_t *ref, refc_type_t n)
	Increase reference counter by specified value.
refc_type_t	unrefxn (refc_t *r, void *object, refc_type_t n, void(*dtor)(void *))
	Release references and optionally destroy object.

Typedef Documentation

refc_type_t

typedef unsigned int refc_type_t

Use case:

if (addref(&obj->ref)) { // <-- guarantees object is alive
    use_object(obj);
    unref(&obj->ref, obj);
}

Reference counter type.

Native CPU integer size is usually the fastest option.

Definition at line 47 of file refc.h.

Function Documentation

_Atomic()

typedef _Atomic

(

refc_type_t

)

Atomic reference counter type.

addrefn()

refc_type_t addrefn	(	refc_t *	ref,
		refc_type_t	n )

Increase reference counter by specified value.

This function attempts to increase reference counter by /n/.

Parameters

ref	: pointer to reference counter.
n	: number of references to add.

Returns

: refcount value AFTER addref(). Returned value of Zero means this object is either dead or can not increase its refcounter anymore (overflow)

Note

This function fails if reference counter is zero.

This function fails if incrementing the counter would cause an overflow.

If /n/ is zero, function performs a liveness check.

(see refc.h for full comments)

This function attempts to increase reference counter by n (user defined integer type variable or integer literal, e.g. addrefn(&ref, 10)).

Definition at line 39 of file refc.c.

unrefxn()

refc_type_t unrefxn	(	refc_t *	r,
		void *	object,
		refc_type_t	n,
		void(*	dtor )(void *) )

Release references and optionally destroy object.

Decrease reference counter by /n/. When reference counter reaches zero, destructor function /dtor/ is called.

Parameters

r	: pointer to reference counter.
object	: object controlled by the reference counter.
n	: number of references to release. If n is zero, function performs a liveness check. If /n/ is greater than current reference count, reference counter is decremented until it reaches zero. Destructor function is called exactly once.
dtor	: destructor function. standart C function free() can be used here If dtor is NULL, object is not destroyed even when reference counter reaches zero, possibly creating a memory leak.

Returns

Value of a refcounter before unreferencing. Value of 1 means object was deleted i.e. if (unrefxn( ... ) == 1) puts("Last reference gone, object has been deleted");

Value of 0 is returned when some fatal eeror is occured: attempt to unref the object which is being deleted; pointer to the r is NULL

Note

Destructor function receives /object/ as its argument. If /object/ is NULL, reference counter pointer /r/ is passed to the destructor instead. If reference counter /ref/ is the first member of the object (i.e. embedded into the object), /object/ may be NULL.

It is safe to call unrefxn() with the same /n/ value that was previously passed to addrefn(), even if current reference count becomes smaller than /n/.

(see refc.h for full comments)

Decrease reference counter by /n/. When reference counter reaches zero, destructor function /dtor/ is called: in case of n > 0, object is unreferenced one by one so the destructor is called exactly once, even if n is larger than current ref counter value

Definition at line 75 of file refc.c.