picotm  0.7.0
Typedefs | Functions
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
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_objThe shared-ref16 object.
dataUser 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_objThe shared-ref16 object.
dataUser data.
[out]errorReturns 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_objThe shared-ref16 object.
dataUser data.
[out]errorReturns 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
selfThe shared-ref16 object.
dataUser data.
condAn optional condition to test if the reference should be released.
final_refAn 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
selfThe shared-ref16 object.
[out]errorReturns 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
selfThe 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
selfThe shared-ref16 object.
dataUser data.
condAn optional condition to test if the reference should be acquired.
first_refAn optional function to initialize the object when the first reference gets acquired.
[out]errorReturns 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.