Reference counting

Data Structures
struct	sys_refcount
	Reference counter. More...
struct	sys_ref
	Reference of an object. More...

Macros
#define	SYS_REFCOUNT_INITIALIZER   { .value = ATOMIC_INIT(1) }
	Static initializer for a sys_refcount.
#define	SYS_REF_INITIALIZER   { .refcount = SYS_REFCOUNT_INITIALIZER }
	Static initializer for a Reference counting.

Typedefs
typedef void(*	sys_ref_release_t) (struct sys_ref *const ref)
	Release handler called once the last reference is dropped.

Functions
static void	sys_refcount_init (struct sys_refcount *const rc)
	Initialize a reference counter to one.
static void	sys_refcount_inc (struct sys_refcount *const rc)
	Increment a reference counter.
static bool	sys_refcount_dec (struct sys_refcount *const rc)
	Decrement a reference counter.
static void	sys_ref_init (struct sys_ref *const ref)
	Initialize a reference to one.
static void	sys_ref_get (struct sys_ref *const ref)
	Increase reference of an object.
static bool	sys_ref_put (struct sys_ref *const ref, const sys_ref_release_t release)
	Decrease reference of an object.

Detailed Description

Version

0.1.0

Macro Definition Documentation

SYS_REF_INITIALIZER

#define SYS_REF_INITIALIZER   { .refcount = SYS_REFCOUNT_INITIALIZER }

#include <ref.h>

Static initializer for a Reference counting.

Establishes the first reference at compile time, equivalent to calling sys_ref_init():

struct my_obj obj = {
        .ref = SYS_REF_INITIALIZER,
        ...
};

SYS_REFCOUNT_INITIALIZER

#define SYS_REFCOUNT_INITIALIZER   { .value = ATOMIC_INIT(1) }

#include <ref.h>

Static initializer for a sys_refcount.

Initializes the counter to one at compile time, equivalent to calling sys_refcount_init().

Typedef Documentation

sys_ref_release_t

typedef void(* sys_ref_release_t) (struct sys_ref *const ref)

#include <ref.h>

Release handler called once the last reference is dropped.

Parameters

[in]

ref

Reference embedded in the object being released

Function Documentation

sys_ref_get()

void sys_ref_get ( struct sys_ref *const ref )

inlinestatic

#include <ref.h>

Increase reference of an object.

Only safe to call while the caller already holds a valid reference, which keeps the object alive and the counter non-zero. It cannot be used to take the first reference (see sys_ref_init()) or to revive an object whose references may have already dropped to zero.

Parameters

[in]

ref

Reference

sys_ref_init()

void sys_ref_init ( struct sys_ref *const ref )

inlinestatic

#include <ref.h>

Initialize a reference to one.

Must be called once before any other operation on the reference, by whoever creates the object. It establishes the first reference, owned by the caller and released with sys_ref_put().

Parameters

[in]

ref

Reference

sys_ref_put()

bool sys_ref_put ( struct sys_ref *const ref, const sys_ref_release_t release )

inlinestatic

#include <ref.h>

Decrease reference of an object.

Decrement the reference and call release once the last one is dropped. After this call the caller must no longer access the object, as it may already have been released.

The release handler recovers the enclosing object with CONTAINER_OF and frees the resources it holds:

struct my_obj {
        struct sys_ref ref;
        ...
};
 
static void my_obj_release(struct sys_ref *const ref)
{
        struct my_obj *obj = CONTAINER_OF(ref, struct my_obj, ref);
 
        k_free(obj);
}
 
sys_ref_put(&obj->ref, my_obj_release);

Parameters

[in]	ref	Reference
[in]	release	Handler releasing the object

Return values

true	if the object was released
false	otherwise

sys_refcount_dec()

bool sys_refcount_dec ( struct sys_refcount *const rc )

inlinestatic

#include <ref.h>

Decrement a reference counter.

The counter must not be zero. A saturated counter stays pinned and never reaches zero.

Parameters

[in]

rc

Reference counter

Return values

true	if the counter reached zero
false	otherwise

sys_refcount_inc()

void sys_refcount_inc ( struct sys_refcount *const rc )

inlinestatic

#include <ref.h>

Increment a reference counter.

The caller must already hold a reference, hence the counter must not be zero. Once the counter is saturated it stays pinned.

Parameters

[in]

rc

Reference counter

sys_refcount_init()

void sys_refcount_init ( struct sys_refcount *const rc )

inlinestatic

#include <ref.h>

Initialize a reference counter to one.

Parameters

[in]

rc

Reference counter