refc.c File Reference

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

Go to the source code of this file.

Functions
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.

Function Documentation

addrefn()

refc_type_t addrefn	(	refc_t *	ref,
		refc_type_t	n )

Increase reference counter by specified value.

(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)).

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.

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.

(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

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/.

Definition at line 75 of file refc.c.