Files | Data Structures | Macros | Typedefs | Enumerations | Functions
The Module Helper Library

Different modules often share a number of fundamental requirements and concepts. Picotm comes with a large number of data structures and functions for modules to re-use. This includes locks, tree maps, arrays, reference-counting and more. More...

Files

file  picotm-lib-array.h
 
file  picotm-lib-global-state.h
 Contains global-state helper macros.
 
file  picotm-lib-ptr.h
 
file  picotm-lib-ref.h
 
file  picotm-lib-rwlock.h
 
file  picotm-lib-rwstate.h
 Contains struct picotm_rwstate and helpers.
 
file  picotm-lib-shared-ref-obj.h
 Contains struct picotm_shared_ref16_obj and helper functions.
 
file  picotm-lib-shared-state.h
 Contains shared-state helper macros.
 
file  picotm-lib-shared-treemap.h
 Contains struct picotm_shared_treemap and helper functions.
 
file  picotm-lib-slist.h
 Contains struct picotm_slist and helpers.
 
file  picotm-lib-spinlock.h
 Contains struct picotm_spinlock and helper functions.
 
file  picotm-lib-state.h
 Contains state helper macros.
 
file  picotm-lib-tab.h
 
file  picotm-lib-thread-state.h
 Contains thread-state helper macros.
 
file  picotm-lib-treemap.h
 Contains struct picotm_treemap and helpers.
 

Data Structures

struct  picotm_ref16
 
struct  picotm_rwlock
 A reader-writer lock. More...
 
struct  picotm_rwstate
 
struct  picotm_shared_ref16
 
struct  picotm_shared_ref16_obj
 
struct  picotm_shared_treemap
 Maps keys to values. More...
 
struct  picotm_slist
 Entry in a singly-linked list. More...
 
struct  picotm_spinlock
 Provides an operating-system-neutral, non-recursive spin-lock type. More...
 
struct  picotm_treemap
 Maps keys to values. More...
 

Macros

#define picotm_arrayat(_array, _i)
 
#define picotm_arraybeg(_array)
 
#define picotm_arrayend(_array)
 
#define picotm_arrayfirst(_array)
 
#define picotm_arraylast(_array)
 
#define picotm_arraylen(_array)
 
#define picotm_containerof(ptr, type, member)
 
#define PICOTM_GLOBAL_STATE_GET(_name)
 
#define PICOTM_GLOBAL_STATE_REF(_name, _error)
 
#define PICOTM_GLOBAL_STATE_STATIC_IMPL(_name)
 
#define PICOTM_GLOBAL_STATE_UNREF(_name)
 
#define picotm_ref_count(self)
 
#define picotm_ref_down(self)
 
#define picotm_ref_init(self, count)
 
#define PICOTM_REF_INITIALIZER(__count)
 
#define picotm_ref_up(self)
 
#define PICOTM_RWLOCK_INITIALIZER
 Initializer macro for R/W state variables.
 
#define PICOTM_RWSTATE_INITIALIZER
 Initializer macro for R/W state variables.
 
#define PICOTM_SHARED_REF16_INITIALIZER(count)
 
#define PICOTM_SHARED_REF16_OBJ_INITIALIZER
 
#define PICOTM_SHARED_REF_INITIALIZER(__count)
 
#define PICOTM_SHARED_STATE(_name, _type)
 
#define PICOTM_SHARED_STATE_INITIALIZER
 
#define PICOTM_SHARED_STATE_REF(_name, _self, _error)
 
#define PICOTM_SHARED_STATE_STATIC_IMPL(_name, _type, _init, _uninit)
 
#define PICOTM_SHARED_STATE_TYPE(_name)
 
#define PICOTM_SHARED_STATE_UNREF(_name, _self)
 
#define picotm_sizeof_align(__type)
 Returns the number of size and alignment bytes of a given type. More...
 
#define PICOTM_SLIST_HEAD_INITIALIZER(head_)
 
#define PICOTM_SLIST_ITEM_INITIALIZER
 
#define PICOTM_SPINLOCK_INITIALIZER
 Initializer macro for picotm spin locks.
 
#define PICOTM_STATE(_name, _type)
 
#define PICOTM_STATE_ACQUIRE(_name, _self, _initialize, _error)
 
#define PICOTM_STATE_INITIALIZER
 
#define PICOTM_STATE_RELEASE(_name, _self)
 
#define PICOTM_STATE_STATIC_DECL(_name, _type)
 
#define PICOTM_STATE_STATIC_IMPL(_name, _type, _init, _uninit)
 
#define PICOTM_STATE_TYPE(_name)
 

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_final_ref_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 uintptr_t(* picotm_shared_treemap_value_create_function) (unsigned long long key, struct picotm_shared_treemap *treemap, struct picotm_error *error)
 
typedef void(* picotm_shared_treemap_value_destroy_function) (uintptr_t value, struct picotm_shared_treemap *treemap)
 
typedef int(* picotm_tab_compare_function) (const void *data0, const void *data1)
 
typedef size_t(* picotm_tabwalk_1_function) (void *data0, struct picotm_error *error)
 
typedef size_t(* picotm_tabwalk_2_function) (void *data0, void *data1, struct picotm_error *error)
 
typedef size_t(* picotm_tabwalk_3_function) (void *data0, void *data1, void *data2, struct picotm_error *error)
 
typedef void(* picotm_treemap_value_call_function) (uintptr_t value, unsigned long long key, struct picotm_treemap *treemap, void *data, struct picotm_error *error)
 
typedef uintptr_t(* picotm_treemap_value_create_function) (unsigned long long key, struct picotm_treemap *treemap, struct picotm_error *error)
 
typedef void(* picotm_treemap_value_destroy_function) (uintptr_t value, struct picotm_treemap *treemap)
 

Enumerations

enum  picotm_rwstate_status { PICOTM_RWSTATE_UNLOCKED, PICOTM_RWSTATE_RDLOCKED, PICOTM_RWSTATE_WRLOCKED }
 

Functions

static uintptr_t picotm_address_ceil (uintptr_t addr, size_t algn)
 Rounds an address upwards to the nearest address with the given alignment. More...
 
static PICOTM_BEGIN_DECLS uintptr_t picotm_address_floor (uintptr_t addr, size_t algn)
 Rounds an address downwards to the nearest address with the given alignment. More...
 
static void * picotm_ptr_ceil (const void *ptr, size_t algn)
 Rounds a memory location upwards to the nearest address with the given alignment. More...
 
static ptrdiff_t picotm_ptr_diff (const void *hi, const void *lo)
 Subtracts two memory locations and returns the number of raw bytes between them. More...
 
static void * picotm_ptr_floor (const void *ptr, size_t algn)
 Rounds a memory location downwards to the nearest address with the given alignment. More...
 
PICOTM_NOTHROW void picotm_rwlock_init (struct picotm_rwlock *self)
 
PICOTM_NOTHROW void picotm_rwlock_try_rdlock (struct picotm_rwlock *self, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_rwlock_try_wrlock (struct picotm_rwlock *self, bool upgrade, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_rwlock_uninit (struct picotm_rwlock *self)
 
PICOTM_NOTHROW void picotm_rwlock_unlock (struct picotm_rwlock *self)
 
PICOTM_NOTHROW enum picotm_rwstate_status picotm_rwstate_get_status (const struct picotm_rwstate *self)
 
PICOTM_NOTHROW void picotm_rwstate_init (struct picotm_rwstate *self)
 
PICOTM_NOTHROW void picotm_rwstate_set_status (struct picotm_rwstate *self, enum picotm_rwstate_status status)
 
PICOTM_NOTHROW void picotm_rwstate_try_rdlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_rwstate_try_wrlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_rwstate_uninit (struct picotm_rwstate *self)
 
PICOTM_NOTHROW void picotm_rwstate_unlock (struct picotm_rwstate *self, struct picotm_rwlock *rwlock)
 
uint16_t picotm_shared_ref16_obj_count (struct picotm_shared_ref16_obj *self)
 
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)
 
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)
 
PICOTM_NOTHROW uintptr_t picotm_shared_treemap_find_value (struct picotm_shared_treemap *self, unsigned long long key, picotm_shared_treemap_value_create_function value_create, picotm_shared_treemap_value_destroy_function value_destroy, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_shared_treemap_init (struct picotm_shared_treemap *self, unsigned long key_nbits, unsigned long level_nbits)
 
PICOTM_NOTHROW void picotm_shared_treemap_uninit (struct picotm_shared_treemap *self, picotm_shared_treemap_value_destroy_function value_destroy)
 
static struct picotm_slistpicotm_slist_back (const struct picotm_slist *head)
 
static struct picotm_slistpicotm_slist_begin (const struct picotm_slist *head)
 
static void picotm_slist_cleanup_0 (struct picotm_slist *head, void(*cleanup)(struct picotm_slist *))
 
static void picotm_slist_cleanup_1 (struct picotm_slist *head, void(*cleanup)(struct picotm_slist *, void *), void *data1)
 
static void picotm_slist_cleanup_2 (struct picotm_slist *head, void(*cleanup)(struct picotm_slist *, void *, void *), void *data1, void *data2)
 
static void picotm_slist_dequeue (struct picotm_slist *item)
 
static void picotm_slist_dequeue_front (struct picotm_slist *head)
 
static const struct picotm_slistpicotm_slist_end (const struct picotm_slist *head)
 
static void picotm_slist_enqueue_after (struct picotm_slist *item, struct picotm_slist *newitem)
 
static void picotm_slist_enqueue_back (struct picotm_slist *head, struct picotm_slist *newitem)
 
static void picotm_slist_enqueue_before (struct picotm_slist *item, struct picotm_slist *newitem)
 
static void picotm_slist_enqueue_front (struct picotm_slist *head, struct picotm_slist *newitem)
 
static void picotm_slist_enqueue_sorted (struct picotm_slist *head, struct picotm_slist *newitem, int(*cmp)(struct picotm_slist *, struct picotm_slist *))
 
static struct picotm_slistpicotm_slist_find_0 (const struct picotm_slist *head, _Bool(*test)(const struct picotm_slist *))
 
static struct picotm_slistpicotm_slist_find_1 (const struct picotm_slist *head, _Bool(*test)(const struct picotm_slist *, void *), void *data)
 
static struct picotm_slistpicotm_slist_find_2 (const struct picotm_slist *head, _Bool(*test)(const struct picotm_slist *, void *, void *), void *data1, void *data2)
 
static struct picotm_slistpicotm_slist_front (const struct picotm_slist *head)
 
static struct picotm_slistpicotm_slist_init_head (struct picotm_slist *head)
 
static struct picotm_slistpicotm_slist_init_item (struct picotm_slist *item)
 
static _Bool picotm_slist_is_empty (const struct picotm_slist *head)
 
static _Bool picotm_slist_is_enqueued (const struct picotm_slist *item)
 
static struct picotm_slistpicotm_slist_next (const struct picotm_slist *item)
 
static struct picotm_slistpicotm_slist_prev (const struct picotm_slist *item)
 
static void picotm_slist_uninit_head (struct picotm_slist *head)
 
static void picotm_slist_uninit_item (struct picotm_slist *item)
 
static struct picotm_slistpicotm_slist_walk_0 (const struct picotm_slist *head, size_t(*walk)(struct picotm_slist *))
 
static struct picotm_slistpicotm_slist_walk_1 (const struct picotm_slist *head, size_t(*walk)(struct picotm_slist *, void *data), void *data)
 
static struct picotm_slistpicotm_slist_walk_2 (const struct picotm_slist *head, size_t(*walk)(struct picotm_slist *, void *data1, void *data2), void *data1, void *data2)
 
PICOTM_NOTHROW void picotm_tabfree (void *base)
 
PICOTM_NOTHROW void * picotm_tabresize (void *base, size_t nelems, size_t newnelems, size_t siz, struct picotm_error *error)
 
PICOTM_NOTHROW size_t picotm_tabrwalk_1 (void *base, size_t nelems, size_t siz, picotm_tabwalk_1_function walk, struct picotm_error *error)
 
PICOTM_NOTHROW size_t picotm_tabrwalk_2 (void *base, size_t nelems, size_t siz, picotm_tabwalk_2_function walk, void *data, struct picotm_error *error)
 
PICOTM_NOTHROW size_t picotm_tabuniq (void *base, size_t nelems, size_t siz, picotm_tab_compare_function compare)
 
PICOTM_NOTHROW size_t picotm_tabwalk_1 (void *base, size_t nelems, size_t siz, picotm_tabwalk_1_function walk, struct picotm_error *error)
 
PICOTM_NOTHROW size_t picotm_tabwalk_2 (void *base, size_t nelems, size_t siz, picotm_tabwalk_2_function walk, void *data, struct picotm_error *error)
 
PICOTM_NOTHROW size_t picotm_tabwalk_3 (void *base, size_t nelems, size_t siz, picotm_tabwalk_3_function walk, void *data1, void *data2, struct picotm_error *error)
 
PICOTM_NOTHROW uintptr_t picotm_treemap_find_value (struct picotm_treemap *self, unsigned long long key, picotm_treemap_value_create_function value_create, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_treemap_for_each_value (struct picotm_treemap *self, void *data, picotm_treemap_value_call_function value_call, struct picotm_error *error)
 
PICOTM_NOTHROW void picotm_treemap_init (struct picotm_treemap *self, unsigned long level_nbits)
 
PICOTM_NOTHROW void picotm_treemap_uninit (struct picotm_treemap *self, picotm_treemap_value_destroy_function value_destroy)
 

Detailed Description

Macro Definition Documentation

◆ picotm_arrayat

#define picotm_arrayat (   _array,
  _i 
)

Returns the address of the element at the specified index in a static C array.

◆ picotm_arraybeg

#define picotm_arraybeg (   _array)

Returns the beginning of a static C array.

◆ picotm_arrayend

#define picotm_arrayend (   _array)

Returns the address after a static C array.

◆ picotm_arrayfirst

#define picotm_arrayfirst (   _array)

Returns the address of the first element in a static C array.

◆ picotm_arraylast

#define picotm_arraylast (   _array)

Returns the address of the last element in a static C array.

◆ picotm_arraylen

#define picotm_arraylen (   _array)

Computes the number of elements in a static C array.

◆ picotm_containerof

#define picotm_containerof (   ptr,
  type,
  member 
)

Returns the container of a data structure.

Parameters
ptrA pointer to a data structure.
typeThe type of the container.
memberThe name of the container's member field.
Returns
A pointer to the container data structure.

◆ PICOTM_GLOBAL_STATE_GET

#define PICOTM_GLOBAL_STATE_GET (   _name)

Returns the statically allocated global state. Callers must already hold a reference.

Parameters
_nameThe state name.
Returns
The state.

◆ PICOTM_GLOBAL_STATE_REF

#define PICOTM_GLOBAL_STATE_REF (   _name,
  _error 
)

Acquires a reference to an instance of a global state.

Parameters
_nameThe state name.
[out]_errorReturns an error to the caller.
Returns
The acquired state on success, or NULL on error.

◆ PICOTM_GLOBAL_STATE_STATIC_IMPL

#define PICOTM_GLOBAL_STATE_STATIC_IMPL (   _name)

Expands to the implementation of a global state.

Parameters
_nameThe state name.

◆ PICOTM_GLOBAL_STATE_UNREF

#define PICOTM_GLOBAL_STATE_UNREF (   _name)

Releases a reference to an instance of a global state.

Parameters
_nameThe state name.

◆ picotm_ref_count

#define picotm_ref_count (   self)

Reads a reference counter's value.

Parameters
selfreference counter
Returns
The current value of the reference counter.

◆ picotm_ref_down

#define picotm_ref_down (   self)

Decrements a reference counter.

Parameters
selfA reference counter
Returns
True is this is the final reference, false otherwise.

◆ picotm_ref_init

#define picotm_ref_init (   self,
  count 
)

Initializes a reference counter with the given value.

Parameters
selfA reference counter
countThe initial reference count

◆ PICOTM_REF_INITIALIZER

#define PICOTM_REF_INITIALIZER (   __count)

Initializes a statically allocated reference counter with the given value.

Parameters
__countThe initial reference count

◆ picotm_ref_up

#define picotm_ref_up (   self)

Increments a reference counter.

Parameters
selfA reference counter
Returns
True is this is the first reference, false otherwise.

◆ PICOTM_SHARED_REF16_INITIALIZER

#define PICOTM_SHARED_REF16_INITIALIZER (   count)

Initializes a static reference counter with the given value.

Parameters
countThe initial reference count

◆ PICOTM_SHARED_REF16_OBJ_INITIALIZER

#define PICOTM_SHARED_REF16_OBJ_INITIALIZER

Initializes a statically allocated shared-ref16 object.

◆ PICOTM_SHARED_REF_INITIALIZER

#define PICOTM_SHARED_REF_INITIALIZER (   __count)

Initializes a statically allocated reference counter with the given value.

Parameters
__countThe initial reference count

◆ PICOTM_SHARED_STATE

#define PICOTM_SHARED_STATE (   _name,
  _type 
)

Defines a shared-state structure.

Parameters
_nameThe state name.
_typeThe state type.

◆ PICOTM_SHARED_STATE_INITIALIZER

#define PICOTM_SHARED_STATE_INITIALIZER

Initializes a shared-state structure.

◆ PICOTM_SHARED_STATE_REF

#define PICOTM_SHARED_STATE_REF (   _name,
  _self,
  _error 
)

Acquires a reference to an instance of a shared state.

Parameters
_nameThe state name.
_selfThe state's instance.
[out]_errorReturns an error to the caller.
Returns
The acquired state on success, or NULL on error.

◆ PICOTM_SHARED_STATE_STATIC_IMPL

#define PICOTM_SHARED_STATE_STATIC_IMPL (   _name,
  _type,
  _init,
  _uninit 
)

Expands to the implementation of a shared state.

Parameters
_nameThe state name.
_typeThe state type.
_initThe state's initializer function.
_uninitThe state's clean-up function.

◆ PICOTM_SHARED_STATE_TYPE

#define PICOTM_SHARED_STATE_TYPE (   _name)

Expands to the name of the shared-state structure.

Parameters
_nameThe state name.

◆ PICOTM_SHARED_STATE_UNREF

#define PICOTM_SHARED_STATE_UNREF (   _name,
  _self 
)

Releases a reference to an instance of a shared state.

Parameters
_nameThe state name.
_selfThe state's instance.

◆ picotm_sizeof_align

#define picotm_sizeof_align (   __type)
Parameters
__typeThe type.
Returns
The number of bytes to hold a value of the given type and its aligment bytes.

◆ PICOTM_SLIST_HEAD_INITIALIZER

#define PICOTM_SLIST_HEAD_INITIALIZER (   head_)

Static-initializer macro for singly-linked list heads.

Parameters
head_The singly-linked list's head entry.

◆ PICOTM_SLIST_ITEM_INITIALIZER

#define PICOTM_SLIST_ITEM_INITIALIZER

Static-initializer macro for singly-linked list items.

◆ PICOTM_STATE

#define PICOTM_STATE (   _name,
  _type 
)

Defines a state structure.

Parameters
_nameThe state name.
_typeThe state type.

◆ PICOTM_STATE_ACQUIRE

#define PICOTM_STATE_ACQUIRE (   _name,
  _self,
  _initialize,
  _error 
)

Acquires a state.

Parameters
_nameThe state name.
_initializeTrue to initialize if necessary.
_selfThe state's instance.
[out]_errorReturns an error to the caller.
Returns
The acquired state on success, or NULL if not initialized or on error.

◆ PICOTM_STATE_INITIALIZER

#define PICOTM_STATE_INITIALIZER

Initializes a state structure.

◆ PICOTM_STATE_RELEASE

#define PICOTM_STATE_RELEASE (   _name,
  _self 
)

Releases a previously acquired state.

Parameters
_nameThe state name.
_selfThe state's instance.

◆ PICOTM_STATE_STATIC_DECL

#define PICOTM_STATE_STATIC_DECL (   _name,
  _type 
)

Expands to the forward declaration of a state.

Parameters
_nameThe state name.
_typeThe state type.

◆ PICOTM_STATE_STATIC_IMPL

#define PICOTM_STATE_STATIC_IMPL (   _name,
  _type,
  _init,
  _uninit 
)

Expands to the implementation of a state.

Parameters
_nameThe state name.
_typeThe state type.
_initThe state's initializer function.
_uninitThe state's clean-up function.

◆ PICOTM_STATE_TYPE

#define PICOTM_STATE_TYPE (   _name)

Expands to the name of the state structure.

Parameters
_nameThe state name.

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.

◆ picotm_shared_treemap_value_create_function

typedef uintptr_t(* picotm_shared_treemap_value_create_function) (unsigned long long key, struct picotm_shared_treemap *treemap, struct picotm_error *error)

Invoked by picotm's shared treemap to create a new shared value.

Parameters
keyThe value's key.
treemapThe value's shared treemap.
[out]errorReturns an error from the creator function.
Returns
A pointer to the created value.

◆ picotm_shared_treemap_value_destroy_function

typedef void(* picotm_shared_treemap_value_destroy_function) (uintptr_t value, struct picotm_shared_treemap *treemap)

Invoked by picotm's shared treemap to destroy a value.

Parameters
valueThe value to destroy.
treemapThe value's shared treemap.

◆ picotm_tab_compare_function

typedef int(* picotm_tab_compare_function) (const void *data0, const void *data1)

Invoked by table functions for comparing two elements.

Parameters
data0A table element.
data1A table element.
Returns
A value less, equal, or greater to zero if data0 is less, equal, or greatet than data1.

◆ picotm_tabwalk_1_function

typedef size_t(* picotm_tabwalk_1_function) (void *data0, struct picotm_error *error)

Invoked by table functions when walking over the elements of a table.

Parameters
data0The table element.
[out]errorReturns an error from the module.
Returns
The number of element to advance.

◆ picotm_tabwalk_2_function

typedef size_t(* picotm_tabwalk_2_function) (void *data0, void *data1, struct picotm_error *error)

Invoked by table functions when walking over the elements of a table.

Parameters
data0The table element.
data1An additional argument.
[out]errorReturns an error from the module.
Returns
The number of element to advance.

◆ picotm_tabwalk_3_function

typedef size_t(* picotm_tabwalk_3_function) (void *data0, void *data1, void *data2, struct picotm_error *error)

Invoked by table functions when walking over the elements of a table.

Parameters
data0The table element.
data1An additional argument.
data2An additional argument.
[out]errorReturns an error from the module.
Returns
The number of element to advance.

◆ picotm_treemap_value_call_function

typedef void(* picotm_treemap_value_call_function) (uintptr_t value, unsigned long long key, struct picotm_treemap *treemap, void *data, struct picotm_error *error)

Invoked by picotm's treemap to call a value.

Parameters
valueThe value.
keyThe value's key.
treemapThe value's treemap.
dataUser data.
[out]errorReturns an error from the creator function.

◆ picotm_treemap_value_create_function

typedef uintptr_t(* picotm_treemap_value_create_function) (unsigned long long key, struct picotm_treemap *treemap, struct picotm_error *error)

Invoked by picotm's treemap to create a new value.

Parameters
keyThe value's key.
treemapThe value's treemap.
[out]errorReturns an error from the creator function.
Returns
A pointer to the created value.

◆ picotm_treemap_value_destroy_function

typedef void(* picotm_treemap_value_destroy_function) (uintptr_t value, struct picotm_treemap *treemap)

Invoked by picotm's treemap to destroy a value.

Parameters
valueThe value to destroy.
treemapThe value's treemap.

Enumeration Type Documentation

◆ picotm_rwstate_status

Signals a shared state's status wrt. a transaction

Enumerator
PICOTM_RWSTATE_UNLOCKED 

The transaction has not acquired the lock.

PICOTM_RWSTATE_RDLOCKED 

The transaction has acquired a reader lock.

PICOTM_RWSTATE_WRLOCKED 

The transaction has acquired a writer lock.

Function Documentation

◆ picotm_address_ceil()

static uintptr_t picotm_address_ceil ( uintptr_t  addr,
size_t  algn 
)
inlinestatic
Parameters
addrA memory address.
algnThe alignment of the result address.
Returns
The next higher address with the given alignment.

◆ picotm_address_floor()

static PICOTM_BEGIN_DECLS uintptr_t picotm_address_floor ( uintptr_t  addr,
size_t  algn 
)
inlinestatic
Parameters
addrA memory address.
algnThe alignment of the result address.
Returns
The next lower address with the given alignment.

◆ picotm_ptr_ceil()

static void* picotm_ptr_ceil ( const void *  ptr,
size_t  algn 
)
inlinestatic
Parameters
ptrA pointer to a memory location.
algnThe alignment of the result memory location.
Returns
The next higher memory location with the given alignment.

◆ picotm_ptr_diff()

static ptrdiff_t picotm_ptr_diff ( const void *  hi,
const void *  lo 
)
inlinestatic
Parameters
hiThe higher memory location.
loThe lower memory location.
Returns
The number of bytes between lo an hi.

◆ picotm_ptr_floor()

static void* picotm_ptr_floor ( const void *  ptr,
size_t  algn 
)
inlinestatic
Parameters
ptrA pointer to a memory location.
algnThe alignment of the result memory location.
Returns
The next lower memory location with the given alignment.

◆ picotm_rwlock_init()

PICOTM_NOTHROW void picotm_rwlock_init ( struct picotm_rwlock self)

Initializes a reader-writer lock.

Parameters
selfThe reader-writer lock to initialize.

◆ picotm_rwlock_try_rdlock()

PICOTM_NOTHROW void picotm_rwlock_try_rdlock ( struct picotm_rwlock self,
struct picotm_error error 
)

Tries to acquire a read lock. If the lock could not be acquired, the error parameter will return a conflict.

Parameters
selfThe reader lock to acquire.
[out]errorReturns a error.

◆ picotm_rwlock_try_wrlock()

PICOTM_NOTHROW void picotm_rwlock_try_wrlock ( struct picotm_rwlock self,
bool  upgrade,
struct picotm_error error 
)

Tries to acquire a writer lock or upgrade an acquired reader lock to a writer lock. If the lock could not be acquired, the error parameter will return a conflict.

Parameters
selfThe writer lock to acquire.
upgradeTrue to upgrade a previously acquired reader lock.
[out]errorReturns a error.

◆ picotm_rwlock_uninit()

PICOTM_NOTHROW void picotm_rwlock_uninit ( struct picotm_rwlock self)

Uninitializes a reader-writer lock.

Parameters
selfThe reader-writer lock to uninitialize.

◆ picotm_rwlock_unlock()

PICOTM_NOTHROW void picotm_rwlock_unlock ( struct picotm_rwlock self)

Releases a reader-writer lock.

Parameters
selfThe reader-writer lock to release.

◆ picotm_rwstate_get_status()

PICOTM_NOTHROW enum picotm_rwstate_status picotm_rwstate_get_status ( const struct picotm_rwstate self)

Returns a reader/writer state's current status.

Parameters
selfThe reader/writer state.
Returns
The reader/writer state's status.

◆ picotm_rwstate_init()

PICOTM_NOTHROW void picotm_rwstate_init ( struct picotm_rwstate self)

Initializes a reader-writer state.

Parameters
selfThe reader-writer state to initialize.

◆ picotm_rwstate_set_status()

PICOTM_NOTHROW void picotm_rwstate_set_status ( struct picotm_rwstate self,
enum picotm_rwstate_status  status 
)

Sets a reader/writer state's status.

Parameters
selfThe reader/writer state.
statusThe status to set.
Returns
The reader/writer state's status.

◆ picotm_rwstate_try_rdlock()

PICOTM_NOTHROW void picotm_rwstate_try_rdlock ( struct picotm_rwstate self,
struct picotm_rwlock rwlock,
struct picotm_error error 
)

Tries to acquire a reader lock for the state variable. If the lock could not be acquired, the error parameter will return a conflict.

Parameters
selfThe reader/writer state.
rwlockThe reader lock to acquire.
[out]errorReturns a error.

◆ picotm_rwstate_try_wrlock()

PICOTM_NOTHROW void picotm_rwstate_try_wrlock ( struct picotm_rwstate self,
struct picotm_rwlock rwlock,
struct picotm_error error 
)

Tries to acquire a writer lock for the state variable or upgrade an acquired reader lock to a writer lock. If the lock could not be acquired, the error parameter will return a conflict.

Parameters
selfThe reader/writer state.
rwlockThe reader lock to acquire.
[out]errorReturns a error.

◆ picotm_rwstate_uninit()

PICOTM_NOTHROW void picotm_rwstate_uninit ( struct picotm_rwstate self)

Uninitializes a reader-writer state.

Parameters
selfThe reader-writer state to uninitialize.

◆ picotm_rwstate_unlock()

PICOTM_NOTHROW void picotm_rwstate_unlock ( struct picotm_rwstate self,
struct picotm_rwlock rwlock 
)

Releases a reader-writer lock.

Parameters
selfThe reader/writer state.
rwlockThe reader/writer lock to release.

◆ picotm_shared_ref16_obj_count()

uint16_t picotm_shared_ref16_obj_count ( struct picotm_shared_ref16_obj self)

Reads the value of a shared-ref16 object's counter.

Parameters
selfThe shared-ref16 object.
Returns
The current value of the reference counter.

◆ 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.

◆ picotm_shared_treemap_find_value()

PICOTM_NOTHROW uintptr_t picotm_shared_treemap_find_value ( struct picotm_shared_treemap self,
unsigned long long  key,
picotm_shared_treemap_value_create_function  value_create,
picotm_shared_treemap_value_destroy_function  value_destroy,
struct picotm_error error 
)

Retrieves the value for a key from a shared treemap.

Parameters
selfThe shared treemap.
keyThe value's key.
value_createThe creator function for shared values.
value_destroyThe destroy function for shared values.
[out]errorReturns an error from the look-up function.
Returns
The key's element.

◆ picotm_shared_treemap_init()

PICOTM_NOTHROW void picotm_shared_treemap_init ( struct picotm_shared_treemap self,
unsigned long  key_nbits,
unsigned long  level_nbits 
)

Initializes a shared treemap.

Parameters
selfThe shared treemap to initialize.
key_nbitsThe maximum number of bits per key.
level_nbitsThe number of bits per directory level.

◆ picotm_shared_treemap_uninit()

PICOTM_NOTHROW void picotm_shared_treemap_uninit ( struct picotm_shared_treemap self,
picotm_shared_treemap_value_destroy_function  value_destroy 
)

Uninitializes a shared treemap.

Parameters
selfThe shared treemap to initialize.
value_destroyThe destroy function for shared values.

◆ picotm_slist_back()

static struct picotm_slist* picotm_slist_back ( const struct picotm_slist head)
inlinestatic

Returns the final item of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
Returns
The first entry in the singly-linked list, or the list head if the list is empty.

◆ picotm_slist_begin()

static struct picotm_slist* picotm_slist_begin ( const struct picotm_slist head)
inlinestatic

Returns the first entry in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
Returns
The first entry in the singly-linked list, or the list head if the list is empty.

◆ picotm_slist_cleanup_0()

static void picotm_slist_cleanup_0 ( struct picotm_slist head,
void(*)(struct picotm_slist *)  cleanup 
)
inlinestatic

Cleans up all items of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
cleanupThe clean-up function for each item.

◆ picotm_slist_cleanup_1()

static void picotm_slist_cleanup_1 ( struct picotm_slist head,
void(*)(struct picotm_slist *, void *)  cleanup,
void *  data1 
)
inlinestatic

Cleans up all items of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
cleanupThe clean-up function for each item.
data1The first data parameter for the walk function.

◆ picotm_slist_cleanup_2()

static void picotm_slist_cleanup_2 ( struct picotm_slist head,
void(*)(struct picotm_slist *, void *, void *)  cleanup,
void *  data1,
void *  data2 
)
inlinestatic

Cleans up all items of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
cleanupThe clean-up function for each item.
data1The first data parameter for the walk function.
data2The second data parameter for the walk function.

◆ picotm_slist_dequeue()

static void picotm_slist_dequeue ( struct picotm_slist item)
inlinestatic

Dequeues an item of a singly-linked list.

Parameters
itemThe singly-linked list's exiting entry.

◆ picotm_slist_dequeue_front()

static void picotm_slist_dequeue_front ( struct picotm_slist head)
inlinestatic

Dequeues the front item of a singly-linked list.

Parameters
headThe singly-linked list's head entry.

◆ picotm_slist_end()

static const struct picotm_slist* picotm_slist_end ( const struct picotm_slist head)
inlinestatic

Returns the terminating entry in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
Returns
The terminating entry in the singly-linked list.

◆ picotm_slist_enqueue_after()

static void picotm_slist_enqueue_after ( struct picotm_slist item,
struct picotm_slist newitem 
)
inlinestatic

Enqueues an item to a singly-linked list after an existing item.

Parameters
itemThe singly-linked list's exiting entry.
newitemThe new entry for the singly-linked list.

◆ picotm_slist_enqueue_back()

static void picotm_slist_enqueue_back ( struct picotm_slist head,
struct picotm_slist newitem 
)
inlinestatic

Enqueues an item at the end of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
newitemThe new entry for the singly-linked list.

◆ picotm_slist_enqueue_before()

static void picotm_slist_enqueue_before ( struct picotm_slist item,
struct picotm_slist newitem 
)
inlinestatic

Enqueues an item to a singly-linked list before an existing item.

Parameters
itemThe singly-linked list's exiting entry.
newitemThe new entry for the singly-linked list.

◆ picotm_slist_enqueue_front()

static void picotm_slist_enqueue_front ( struct picotm_slist head,
struct picotm_slist newitem 
)
inlinestatic

Enqueues an item at the beginning of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
newitemThe new entry for the singly-linked list.

◆ picotm_slist_enqueue_sorted()

static void picotm_slist_enqueue_sorted ( struct picotm_slist head,
struct picotm_slist newitem,
int(*)(struct picotm_slist *, struct picotm_slist *)  cmp 
)
inlinestatic

Enqueues an item to a sorted singly-linked list.

Parameters
headThe singly-linked list's head entry.
newitemThe new entry for the singly-linked list.
cmpThe compare-function for sorting the entries.

◆ picotm_slist_find_0()

static struct picotm_slist* picotm_slist_find_0 ( const struct picotm_slist head,
_Bool(*)(const struct picotm_slist *)  test 
)
inlinestatic

Finds an item in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
testThe test function for the find operation.
Returns
An entry in the singly-linked list, or the list head if the entry could not be found.

◆ picotm_slist_find_1()

static struct picotm_slist* picotm_slist_find_1 ( const struct picotm_slist head,
_Bool(*)(const struct picotm_slist *, void *)  test,
void *  data 
)
inlinestatic

Finds an item in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
testThe test function for the find operation.
dataThe data parameter for the test function.
Returns
An entry in the singly-linked list, or the list head if the entry could not be found.

◆ picotm_slist_find_2()

static struct picotm_slist* picotm_slist_find_2 ( const struct picotm_slist head,
_Bool(*)(const struct picotm_slist *, void *, void *)  test,
void *  data1,
void *  data2 
)
inlinestatic

Finds an item in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
testThe test function for the find operation.
data1The first data parameter for the test function.
data2The second data parameter for the test function.
Returns
An entry in the singly-linked list, or the list head if the entry could not be found.

◆ picotm_slist_front()

static struct picotm_slist* picotm_slist_front ( const struct picotm_slist head)
inlinestatic

Returns the front item of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
Returns
The first entry in the singly-linked list, or the list head if the list is empty.

◆ picotm_slist_init_head()

static struct picotm_slist* picotm_slist_init_head ( struct picotm_slist head)
inlinestatic

Initialize the head entry of a singly-linked list.

Parameters
headThe singly-linked list's head entry.
Returns
The list head.

◆ picotm_slist_init_item()

static struct picotm_slist* picotm_slist_init_item ( struct picotm_slist item)
inlinestatic

Initialize an entry of a singly-linked list.

Parameters
itemThe singly-linked list's entry.
Returns
The list entry.

◆ picotm_slist_is_empty()

static _Bool picotm_slist_is_empty ( const struct picotm_slist head)
inlinestatic

Returns true if a singly-linked list is empty.

Parameters
headThe singly-linked list's head entry.
Returns
True if the singly-linked list is empty, or false otherwise.

◆ picotm_slist_is_enqueued()

static _Bool picotm_slist_is_enqueued ( const struct picotm_slist item)
inlinestatic

Returns true if a singly-linked list item is enqueued.

Parameters
itemThe singly-linked list entry.
Returns
True if the entry is enqueued, or false otherwise.

◆ picotm_slist_next()

static struct picotm_slist* picotm_slist_next ( const struct picotm_slist item)
inlinestatic

Returns the next entry in a singly-linked list.

Parameters
itemThe singly-linked list's current entry.
Returns
The next entry in the singly-linked list, or the list head at the end of the list.

◆ picotm_slist_prev()

static struct picotm_slist* picotm_slist_prev ( const struct picotm_slist item)
inlinestatic

Returns the previous entry in a singly-linked list.

Parameters
itemThe singly-linked list's current entry.
Returns
The next entry in the singly-linked list, or the list head at the beginning of the list.

◆ picotm_slist_uninit_head()

static void picotm_slist_uninit_head ( struct picotm_slist head)
inlinestatic

Uninitialize the head entry of a singly-linked list.

Parameters
headThe singly-linked list's head entry.

◆ picotm_slist_uninit_item()

static void picotm_slist_uninit_item ( struct picotm_slist item)
inlinestatic

Uninitialize an entry of a singly-linked list.

Parameters
itemThe singly-linked list's entry.

◆ picotm_slist_walk_0()

static struct picotm_slist* picotm_slist_walk_0 ( const struct picotm_slist head,
size_t(*)(struct picotm_slist *)  walk 
)
inlinestatic

Walks over all items in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
walkThe call-back function for each item.
Returns
The singly-linked list's head entry on success, or the last-processed entry on errors.

◆ picotm_slist_walk_1()

static struct picotm_slist* picotm_slist_walk_1 ( const struct picotm_slist head,
size_t(*)(struct picotm_slist *, void *data)  walk,
void *  data 
)
inlinestatic

Walks over all items in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
walkThe call-back function for each item.
dataThe data parameter for the walk function.
Returns
The singly-linked list's head entry on success, or the last-processed entry on errors.

◆ picotm_slist_walk_2()

static struct picotm_slist* picotm_slist_walk_2 ( const struct picotm_slist head,
size_t(*)(struct picotm_slist *, void *data1, void *data2)  walk,
void *  data1,
void *  data2 
)
inlinestatic

Walks over all items in a singly-linked list.

Parameters
headThe singly-linked list's head entry.
walkThe call-back function for each item.
data1The first data parameter for the walk function.
data2The second data parameter for the walk function.
Returns
The singly-linked list's head entry on success, or the last-processed entry on errors.

◆ picotm_tabfree()

PICOTM_NOTHROW void picotm_tabfree ( void *  base)

Free table memory.

Parameters
baseA pointer to the table's first element.

◆ picotm_tabresize()

PICOTM_NOTHROW void* picotm_tabresize ( void *  base,
size_t  nelems,
size_t  newnelems,
size_t  siz,
struct picotm_error error 
)

Allocate or resize table.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
newnelemsThe new number of elements in the table.
sizThe number of bytes per element.
[out]errorReturns an error from the module.
Returns
A pointer to the resized table on success, or NULL otherwise.

◆ picotm_tabrwalk_1()

PICOTM_NOTHROW size_t picotm_tabrwalk_1 ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tabwalk_1_function  walk,
struct picotm_error error 
)

Walk over table in reversed order.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
walkThe call-back function.
[out]errorReturns an error from the module.
Returns
The number of walked elements.

◆ picotm_tabrwalk_2()

PICOTM_NOTHROW size_t picotm_tabrwalk_2 ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tabwalk_2_function  walk,
void *  data,
struct picotm_error error 
)

Walk over table in reversed order.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
walkThe call-back function.
dataAn additional second argument to the call-back function.
[out]errorReturns an error from the module.
Returns
The number of walked elements.

◆ picotm_tabuniq()

PICOTM_NOTHROW size_t picotm_tabuniq ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tab_compare_function  compare 
)

Filters out duplicate elements

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
compareThe call-back function for comparing elements.
Returns
The new number of elements in the table.

◆ picotm_tabwalk_1()

PICOTM_NOTHROW size_t picotm_tabwalk_1 ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tabwalk_1_function  walk,
struct picotm_error error 
)

Walk over table elements.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
walkThe call-back function.
[out]errorReturns an error from the module.
Returns
The number of walked elements.

◆ picotm_tabwalk_2()

PICOTM_NOTHROW size_t picotm_tabwalk_2 ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tabwalk_2_function  walk,
void *  data,
struct picotm_error error 
)

Walk over table elements.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
walkThe call-back function.
dataAn additional second argument to the call-back function.
[out]errorReturns an error from the module.
Returns
The number of walked elements.

◆ picotm_tabwalk_3()

PICOTM_NOTHROW size_t picotm_tabwalk_3 ( void *  base,
size_t  nelems,
size_t  siz,
picotm_tabwalk_3_function  walk,
void *  data1,
void *  data2,
struct picotm_error error 
)

Walk over table elements.

Parameters
baseA pointer to the table's first element.
nelemsThe number of elements in the table.
sizThe number of bytes per element.
walkThe call-back function.
data1An additional second argument to the call-back function.
data2An additional third argument to the call-back function.
[out]errorReturns an error from the module.
Returns
The number of walked elements.

◆ picotm_treemap_find_value()

PICOTM_NOTHROW uintptr_t picotm_treemap_find_value ( struct picotm_treemap self,
unsigned long long  key,
picotm_treemap_value_create_function  value_create,
struct picotm_error error 
)

Retrieves the value for a key from a treemap.

Parameters
selfThe treemap.
keyThe value's key.
value_createThe creator function for values.
[out]errorReturns an error from the look-up function.
Returns
The key's element.

◆ picotm_treemap_for_each_value()

PICOTM_NOTHROW void picotm_treemap_for_each_value ( struct picotm_treemap self,
void *  data,
picotm_treemap_value_call_function  value_call,
struct picotm_error error 
)

Iterates over all values stored in a treemap.

Parameters
selfThe treemap.
dataUser data.
value_callThe call-back function for values.
[out]errorReturns an error from the look-up function.

◆ picotm_treemap_init()

PICOTM_NOTHROW void picotm_treemap_init ( struct picotm_treemap self,
unsigned long  level_nbits 
)

Initializes a treemap.

Parameters
selfThe treemap to initialize.
level_nbitsThe number of bits per directory level.

◆ picotm_treemap_uninit()

PICOTM_NOTHROW void picotm_treemap_uninit ( struct picotm_treemap self,
picotm_treemap_value_destroy_function  value_destroy 
)

Uninitializes a treemap.

Parameters
selfThe treemap to initialize.
value_destroyThe destroy function for values.