Reference counting

Reference counting with weak pointers. More...

Collaboration diagram for Reference counting:

Detailed Description

Reference counting with weak pointers.

Data Structures
struct	weak_ptr_t
	Weak pointer structure. More...
struct	ref_t
	Reference counting structure. More...

Macros
#define	REF_MAGIC   0x26CB6E4C
	Magic value used in debug builds to check for corruption or invalid use of the ref_t structure.
#define	REF_COUNT(ptr)   ((ptr) == NULL ? 0 : atomic_load_explicit(&((ref_t*)(ptr))->count, memory_order_relaxed))
	Get current reference count.
#define	REF(ptr)
	Increment reference count.
#define	REF_TRY(ptr)
	Increment reference count, but only if the current count is not zero.
#define	UNREF(ptr)
	Decrement reference count.
#define	UNREF_DEFER(ptr)   __attribute__((cleanup(ref_defer_cleanup))) void* CONCAT(p, __COUNTER__) = (ptr)
	RAII-style cleanup for scoped references.

Functions
static void	ref_init (ref_t *ref, void *callback)
	Initialize a reference counter.
static void *	ref_inc (void *ptr)
	Increment reference count.
static void *	ref_inc_try (void *ptr)
	Increment reference count, but only if the current count is not zero.
static void	ref_dec (void *ptr)
	Decrement reference count.
static void	ref_defer_cleanup (void **ptr)
static void	weak_ptr_set (weak_ptr_t *wp, ref_t *ref, void(*callback)(void *), void *arg)
	Set a weak pointer.
static void	weak_ptr_clear (weak_ptr_t *wp)
	Clear a weak pointer.
static void *	weak_ptr_get (weak_ptr_t *wp)
	Upgrade a weak pointer to a strong pointer.

Macro Definition Documentation

REF_MAGIC

#define REF_MAGIC   0x26CB6E4C

Magic value used in debug builds to check for corruption or invalid use of the ref_t structure.

Definition at line 25 of file ref.h.

REF_COUNT

#define REF_COUNT

(

ptr

)

((ptr) == NULL ? 0 : atomic_load_explicit(&((ref_t*)(ptr))->count, memory_order_relaxed))

Get current reference count.

Primarily intended to be used with RCU protected objects to check if they are still alive within a RCU read critical section.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Returns

Current reference count, or 0 if ptr is NULL.

Definition at line 71 of file ref.h.

REF

#define REF

(

ptr

)

Value:

    ({ \
        ref_t* ref = (ref_t*)(ptr); \
        ref_inc(ref); \
        ptr; \
    })

Increment reference count.

Atomically increments the reference counter. Used to avoid the need for a typecast. The magic number checking makes sure we cant accidentally misuse this.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Returns

The ptr passed as input

Definition at line 82 of file ref.h.

REF_TRY

#define REF_TRY

(

ptr

)

Value:

    ({ \
        ref_t* ref = (ref_t*)(ptr); \
        ref_inc_try(ref) != NULL ? ptr : NULL; \
    })

Increment reference count, but only if the current count is not zero.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Returns

The ptr passed as input, or NULL if the count was zero.

Definition at line 95 of file ref.h.

UNREF

#define UNREF

(

ptr

)

Value:

    ({ \
        ref_t* ref = (ref_t*)(ptr); \
        ref_dec(ref); \
    })

Decrement reference count.

Atomically decrements the reference counter. Used to avoid the need for a typecast. The magic number checking makes sure we cant accidentally misuse this.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Definition at line 109 of file ref.h.

UNREF_DEFER

#define UNREF_DEFER

(

ptr

)

__attribute__((cleanup(ref_defer_cleanup))) void* CONCAT(p, __COUNTER__) = (ptr)

RAII-style cleanup for scoped references.

Uses GCC's cleanup attribute to automatically call ref_dec when going out of scope.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Definition at line 122 of file ref.h.

Function Documentation

ref_init()

static void ref_init ( ref_t *  ref, void *  callback  )

inlinestatic

Initialize a reference counter.

Parameters

ref	Pointer to the reference counter structure
callback	Callback to call when count reaches zero

Definition at line 130 of file ref.h.

Here is the call graph for this function:

Here is the caller graph for this function:

ref_inc()

static void * ref_inc ( void *  ptr )

inlinestatic

Increment reference count.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Returns

The ptr passed as input

Definition at line 147 of file ref.h.

ref_inc_try()

static void * ref_inc_try ( void *  ptr )

inlinestatic

Increment reference count, but only if the current count is not zero.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Returns

The ptr passed as input, or NULL if the count was zero.

Definition at line 166 of file ref.h.

Here is the caller graph for this function:

ref_dec()

static void ref_dec ( void *  ptr )

inlinestatic

Decrement reference count.

If count reaches zero it calls the registered cleanup function.

Parameters

ptr	Pointer to the struct containing ref_t as its first member, can be NULL.

Definition at line 195 of file ref.h.

Here is the call graph for this function:

Here is the caller graph for this function:

ref_defer_cleanup()

static void ref_defer_cleanup ( void **  ptr )

inlinestatic

Definition at line 237 of file ref.h.

Here is the call graph for this function:

weak_ptr_set()

static void weak_ptr_set ( weak_ptr_t *  wp, ref_t *  ref, void(*)(void *)  callback, void *  arg  )

inlinestatic

Set a weak pointer.

The provided callback must not attempt to access the weak ptr as that would cause a deadlock.

Parameters

wp	Pointer to the weak pointer structure
ref	Pointer to the reference counting structure to point to, can be NULL.
callback	Callback function to call when the strong reference count reaches zero.
arg	Argument to pass to the callback function.

Definition at line 252 of file ref.h.

Here is the call graph for this function:

Here is the caller graph for this function:

weak_ptr_clear()

static void weak_ptr_clear ( weak_ptr_t *  wp )

inlinestatic

Clear a weak pointer.

Will not invoke the callback.

Parameters

wp	Pointer to the weak pointer structure.

Definition at line 280 of file ref.h.

Here is the call graph for this function:

weak_ptr_get()

static void * weak_ptr_get ( weak_ptr_t *  wp )

inlinestatic

Upgrade a weak pointer to a strong pointer.

If the strong reference count is zero, NULL is returned.

Parameters

wp	Pointer to the weak pointer structure

Returns

On success, pointer to the struct containing ref_t as its first member. On failure, NULL.

Definition at line 316 of file ref.h.

Here is the call graph for this function:

Here is the caller graph for this function: