picotm-lib-shared-ref-obj.h File Reference

Contains struct picotm_shared_ref16_obj and helper functions. More...

#include "compiler.h"
#include "picotm-lib-ref.h"
#include "picotm-lib-spinlock.h"

Typedefs
typedef bool(*	picotm_shared_ref16_obj_condition_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)
typedef void(*	picotm_shared_ref16_obj_first_ref_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)
typedef void(*	picotm_shared_ref16_obj_final_ref_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)

Functions
void	picotm_shared_ref16_obj_init (struct picotm_shared_ref16_obj *self, struct picotm_error *error)
void	picotm_shared_ref16_obj_uninit (struct picotm_shared_ref16_obj *self)
void	picotm_shared_ref16_obj_up (struct picotm_shared_ref16_obj *self, void *data, picotm_shared_ref16_obj_condition_function cond, picotm_shared_ref16_obj_first_ref_function first_ref, struct picotm_error *error)
void	picotm_shared_ref16_obj_down (struct picotm_shared_ref16_obj *self, void *data, picotm_shared_ref16_obj_condition_function cond, picotm_shared_ref16_obj_final_ref_function final_ref)

Detailed Description

The data structure struct picotm_shared_ref16_obj is the base for objects with shared reference counting. It maintains the counter and guarantees synchronization with the initializer and finalizer code. The counter of picotm_shared_ref16_obj is 16-bit wide of type struct picotm_shared_ref16. Additional shared-reference-counter types can be added for use cases with different requirements.

Instances of struct picotm_shared_ref16 are typically stored in reference-counted data structures like this.

struct ref_counted {
    struct picotm_shared_ref16_obj ref_obj;

    // additional data
};

An instance of picotm_shared_ref16_obj is initialized with a call to picotm_shared_ref16_obj_init() and cleaned up with a call to picotm_shared_ref16_obj_uninit(). These functions receive an instance of struct picotm_shared_ref16_obj and the init function also receives an instance of struct picotm_error, which returns error state. These functions are called in the init and un-init functions of the parent class.

void
ref_counted_init(struct ref_counted* self, struct picotm_error* error)
{
    picotm_shared_ref16_obj_init(&self->ref_obj, error);
    if (picotm_error_is_set(error)) {
        return;
    }

    // additional initialization
}

At this point, the reference counter is initialized to zero and references to the object can be acquired. Next is the clean-up code.

void
ref_counted_uninit(struct ref_counted* self)
{
    // additional clean-up code

    picotm_shared_ref16_obj_uninit(&self->ref_obj);
    if (picotm_error_is_set(error)) {
        return;
    }
}

References to an object are acquired with a call to picotm_shared_ref16_obj_up(). The parameters of the function consist of and instance of struct picotm_shared_ref16_obj, additional user data, an optional conditional function, and optional initializer function and in instance of struct picotm_error, which returns an error state to the caller.

If supplied, the optional conditional function can perform a test before the reference is acquired. If the test fails with a value of false, the reference is not acquired.

If supplied, the optional initializer function initializes the object if, and only if, the first reference is acquired.

The reference-counted object using struct picotm_shared_ref16_obj will typically provide wrapper functions around picotm_shared_ref16_obj_up().

static bool
up_cond(struct picotm_shared_ref16_obj* ref_obj, void* data,
        struct picotm_error* error)
{
    struct ref_counted* self = picotm_containerof(ref_obj,
                                                  struct ref_counted,
                                                  ref_obj);

    return true; // Perform a test and return success or failure.
}

static void
first_ref(struct picotm_shared_ref16_obj* ref_obj, void* data,
          struct picotm_error* error)
{
    struct ref_counted* self = picotm_containerof(ref_obj,
                                                  struct ref_counted,
                                                  ref_obj);

    // Perform additional initalization when acquiring the
    // first reference.
}

void
ref_counted_up(struct ref_counted* self, struct picotm_error* error)
{
    picotm_shared_ref16_obj_up(&self->ref_obj, NULL, up_cond,
                               first_ref, error);
}

With the example code above, users of struct ref_counted call ref_counted_up() to acquire a reference on an instance of the data structure.

The code for releasing a reference is very similar to code for acquiring one. This time the function picotm_shared_ref16_obj_down() is used.

static bool
down_cond(struct picotm_shared_ref16_obj* ref_obj, void* data,
          struct picotm_error* error)
{
    struct ref_counted* self = picotm_containerof(ref_obj,
                                                  struct ref_counted,
                                                  ref_obj);

    return true; // Perform a test and return success or failure.
}

static void
final_ref(struct picotm_shared_ref16_obj* ref_obj, void* data,
          struct picotm_error* error)
{
    struct ref_counted* self = picotm_containerof(ref_obj,
                                                  struct ref_counted,
                                                  ref_obj);

    // Perform additional cleanup when releasing the
    // final reference.
}

void
ref_counted_down(struct ref_counted* self)
{
    picotm_shared_ref16_obj_down(&self->ref_obj, NULL, down_cond,
                                 final_ref);
}

Typedef Documentation

picotm_shared_ref16_obj_condition_function

typedef bool(* picotm_shared_ref16_obj_condition_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)

Invoked by picotm's shared-ref16 object to test if a reference shall be acquired ore released.

Parameters

ref_obj	The shared-ref16 object.
data	User data.
error[out]	Returns an error to the caller.

Returns

True if the performed test succeeds, or false otherwise.

picotm_shared_ref16_obj_final_ref_function

typedef void(* picotm_shared_ref16_obj_final_ref_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)

Invoked by picotm's shared-ref16 object to finalize an object after releasing the final refrence.

Parameters

	ref_obj	The shared-ref16 object.
	data	User data.
[out]	error	Returns an error to the caller.

picotm_shared_ref16_obj_first_ref_function

typedef void(* picotm_shared_ref16_obj_first_ref_function) (struct picotm_shared_ref16_obj *ref_obj, void *data, struct picotm_error *error)

Invoked by picotm's shared-ref16 object to initialize the object after acquiring the first refrence.

Parameters

	ref_obj	The shared-ref16 object.
	data	User data.
[out]	error	Returns an error to the caller.

Function Documentation

picotm_shared_ref16_obj_down()

void picotm_shared_ref16_obj_down	(	struct picotm_shared_ref16_obj *	self,
		void *	data,
		picotm_shared_ref16_obj_condition_function	cond,
		picotm_shared_ref16_obj_final_ref_function	final_ref
	)

Releases a reference on the shared-ref16 object.

Parameters

self	The shared-ref16 object.
data	User data.
cond	An optional condition to test if the reference should be released.
final_ref	An optional function to finalize the object when the final reference gets released.

The conditional and finalizer functions are synchronized with the reference counter. The down function internally locks the shared-ref16 object while performing these operations.

picotm_shared_ref16_obj_init()

void picotm_shared_ref16_obj_init	(	struct picotm_shared_ref16_obj *	self,
		struct picotm_error *	error
	)

Initializes a shared-ref16 object.

Parameters

	self	The shared-ref16 object.
[out]	error	Returns an error to the caller.

picotm_shared_ref16_obj_uninit()

void picotm_shared_ref16_obj_uninit

(

struct picotm_shared_ref16_obj *

self

)

Uninitializes a shared-ref16 object.

Parameters

self	The shared-ref16 object.

picotm_shared_ref16_obj_up()

void picotm_shared_ref16_obj_up	(	struct picotm_shared_ref16_obj *	self,
		void *	data,
		picotm_shared_ref16_obj_condition_function	cond,
		picotm_shared_ref16_obj_first_ref_function	first_ref,
		struct picotm_error *	error
	)

Acquires a reference on the shared-ref16 object.

Parameters

	self	The shared-ref16 object.
	data	User data.
	cond	An optional condition to test if the reference should be acquired.
	first_ref	An optional function to initialize the object when the first reference gets acquired.
[out]	error	Returns an error to the caller.

The conditional and initializer functions are synchronized with the reference counter. The up function internally locks the shared-ref16 object while performing these operations.