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.
static void	initref (refc_t *ref)
	Initialize reference counter.
static void	initrefn (refc_t *ref, refc_type_t n)
	Initialize reference counter with specified value.
refc_type_t	addrefn (refc_t *ref, refc_type_t n)
	Increase reference counter by specified value.
static refc_type_t	addref (refc_t *ref)
	Increase reference counter.
refc_type_t	unrefxn (refc_t *r, void *object, refc_type_t n, void(*dtor)(void *))
	Release references and optionally destroy object.
static refc_type_t	unref (refc_t *ref, void *object)
	Release reference and destroy object if no references remain.
static refc_type_t	unrefn (refc_t *ref, void *object, refc_type_t n)
	Release multiple references and destroy object if no references remain.
static refc_type_t	unrefx (refc_t *ref, void *object, void(*dtor)(void *))
	Release reference and call custom destructor.
static refc_type_t	readref (refc_t *r)
	Read refcounter atomically.

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.

addref()

refc_type_t addref ( refc_t * ref )

inlinestatic

Increase reference counter.

Increase reference counter by 1.

Parameters

ref	: pointer to reference counter.

Returns

: refcounter value after increment or 0

Note

This function fails if reference counter is zero.

Definition at line 129 of file refc.h.

References addrefn().

Referenced by tarfs_addref().

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.

Referenced by addref().

initref()

void initref ( refc_t * ref )

inlinestatic

Initialize reference counter.

Set reference counter value to 1.

Parameters

ref	: pointer to reference counter.

Note

If /ref/ is NULL, this function does nothing.

Definition at line 72 of file refc.h.

Referenced by tarfs_mount_memory().

initrefn()

void initrefn ( refc_t * ref, refc_type_t n )

inlinestatic

Initialize reference counter with specified value.

Set reference counter value to /n/.

Parameters

ref	: pointer to reference counter.
n	: initial reference counter value.

Note

If /ref/ is NULL, this function does nothing.

Definition at line 89 of file refc.h.

readref()

refc_type_t readref ( refc_t * r )

inlinestatic

Read refcounter atomically.

Parameters

r	: pointer to reference counter.

Returns

: current counter value

Note

Returned value is intended for diagnostics and statistics. Reference counter value may change immediately after return.

Definition at line 243 of file refc.h.

unref()

refc_type_t unref ( refc_t * ref, void * object )

inlinestatic

Release reference and destroy object if no references remain.

This function is equivalent to:

unrefxn(ref, object, 1, free);

Parameters

ref	: pointer to reference counter.
object	: object controlled by the reference counter.

Returns

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

Definition at line 190 of file refc.h.

References unrefxn().

unrefn()

refc_type_t unrefn ( refc_t * ref, void * object, refc_type_t n )

inlinestatic

Release multiple references and destroy object if no references remain.

This function is equivalent to:

unrefxn(ref, object, n, free);

Parameters

ref	: pointer to reference counter.
object	: object controlled by the reference counter.
n	: number of references to release.

Returns

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

Definition at line 209 of file refc.h.

References unrefxn().

unrefx()

refc_type_t unrefx ( refc_t * ref, void * object, void(* dtor )(void *) )

inlinestatic

Release reference and call custom destructor.

This function is equivalent to:

unrefxn(ref, object, 1, dtor);

Parameters

ref	: pointer to reference counter.
object	: object controlled by the reference counter.
dtor	: destructor function.

Returns

Value of a refcounter before unreferencing. Value of 1 means object was deleted

Definition at line 227 of file refc.h.

References unrefxn().

Referenced by tarfs_unref().

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.

Referenced by unref(), unrefn(), and unrefx().