Classes | Defines | Typedefs | Functions

queue list set
[LIM utility library]

Classes

struct  list_t

Defines

#define LIMQ_NAME_MAX_BYTES   64
#define limq_create(entry_bytes, max_entries, name)   limq_create_ext(entry_bytes, max_entries, name, NULL)
#define limq_enqueue_put(que, obj)   limq_enqueue_put_ext(que, obj, 0)
#define LIMSET_NAME_MAX_BYTES   64

Typedefs

typedef struct list_t list_t
typedef void * limq_handle_t
typedef int(* limq_compare_cb_t )(const void *obj1, const void *obj2)
typedef void * limset_handle_t

Functions

static void list_add_ (list_t *new, list_t *prev, list_t *next)
static void list_del_ (list_t *prev, list_t *next)
static void list_init (list_t *list)
static void list_add (list_t *new, list_t *head)
static void list_add_tail (list_t *new, list_t *head)
static void list_del (list_t *entry)
static void list_del_init (list_t *entry)
static int list_empty (const list_t *head)
static int list_entries (const list_t *head)
limq_handle_t limq_create_ext (int entry_bytes, int max_entries, const char *name, limq_compare_cb_t compare)
void limq_reset (limq_handle_t que)
void limq_destroy (limq_handle_t que)
void * limq_enqueue_get (limq_handle_t que)
int limq_enqueue_release (limq_handle_t que, const void *obj)
int limq_enqueue_put_ext (limq_handle_t que, const void *obj, int force_top)
void * limq_dequeue_get (limq_handle_t que)
int limq_dequeue_hold (limq_handle_t que, const void *obj)
int limq_dequeue_release (limq_handle_t que, const void *obj)
int limq_dequeue_put (limq_handle_t que, const void *obj)
int limq_entries (limq_handle_t que)
int limq_obj_ref_count (limq_handle_t que, const void *obj)
limset_handle_t limset_create (int entry_bytes, int max_entries, const char *name)
void limset_destroy (limset_handle_t set)
void * limset_next (limset_handle_t set, void *obj)
int limset_consume (limset_handle_t set, const void *obj)
void * limset_new (limset_handle_t set)
int limset_commit (limset_handle_t set, const void *obj)
int limset_entries (limset_handle_t set)

Detailed Description

this module implements list, queue and set. 'list' provides doubly-linked list support, 'queue' provides FIFO support with object reference count and object holding support, 'set' provides random access to a given set of objects.


Define Documentation

#define limq_create (   entry_bytes,
  max_entries,
  name 
)    limq_create_ext(entry_bytes, max_entries, name, NULL)

create lim queue handle.

Parameters:
entry_bytes bytes of each entry
max_entries maximum allowed queued entries
name queue name for debug tracking purpose, can be NULL.
Returns:
queue handle if successful, NULL otherwise.
#define limq_enqueue_put (   que,
  obj 
)    limq_enqueue_put_ext(que, obj, 0)

put back writable queue entry and advance queue pointer next call to limq_enqueue_get() would return next writable object in the queue.

Parameters:
que queue handle.
obj data object pointer returned by limq_enqueue_get().
Returns:
0 if successful and queue pointer advanced 1 if successful but object is still referenced -1 otherwise.
#define LIMQ_NAME_MAX_BYTES   64

maximum allowed LIMQ name length in bytes.

#define LIMSET_NAME_MAX_BYTES   64

maximum allowed LIMSET name length in bytes.


Typedef Documentation

typedef int(* limq_compare_cb_t)(const void *obj1, const void *obj2)

limq compare callback type.

Parameters:
obj1 user data objet
obj2 user data objet
Returns:
-1 if obj1 is less than obj2 0 if obj1 equals to obj2 1 if obj1 is greater than obj2 the greatest object always gets dequeued first.
typedef void* limq_handle_t

lim queue handle. queue implementation with fix-sized entry, queue is not mutex protected. queue can be created by calling limq_create_ext(), and destroyed or reset by limq_destroy() limq_reset().

object is internally allocated and can be fetched either through limq_dequeue_get() or limq_enqueue_get() depending on queue operation.

on enqueing, object reference counter goes up at limq_enqueue_get(), and goes down by limq_enqueue_put() or limq_enqueue_release().

on dequeing, object reference counter goes up at limq_dequeue_get(), and goes down by limq_dequeue_put() or limq_dequeue_release(). Object only gets released when reference counter goes down to zero.

limq_dequeue_hold() can hold object returned by limq_dequeue_get(), which can later on be released/dereferenced by limq_dequeue_put() or limq_dequeue_release().

limq_dequeue_get() must be paired with either limq_dequeue_put(), or limq_dequeue_release(), and limq_dequeue_hold() must also be paired with either limq_dequeue_put(), or limq_dequeue_release(), and limq_enqueue_get() must be paired with limq_enqueue_put() or limq_enqueue_release().

whether queue pointer is advanced or not depends on the call to release the object, once limq_dequeue_put() is called, queue pointer will be advanced as soon as object reference counter goes down to zero. In other words, if object is referenced (or held) by multiple clients, object will be released and queue pointer be advanced if any one of the clients calls limq_dequeue_put() API on that object, when object reference counter goes down to zero.

typedef void* limset_handle_t

lim set handle. set implementation with fix-sized entry, set is not mutex protected. set internally maintains object order in an FIFO manner, where actual object access order depends on client usage.

set can be created by calling limset_create(), and destroyed by limset_destroy().

object is internally allocated and can be iterated through limset_next() and ref limset_entries(). Object can then be consumed by limset_consume() or simply skipped by doing nothing with it.

on writing, empty object slot can be fetched by limset_new(), and commit back by limset_commit()

typedef struct list_t list_t

Function Documentation

limq_handle_t limq_create_ext ( int  entry_bytes,
int  max_entries,
const char *  name,
limq_compare_cb_t  compare 
)

create ordered lim queue handle.

Parameters:
entry_bytes bytes of each entry
max_entries maximum allowed queued entries
name queue name for debug tracking purpose, can be NULL.
compare callback compare function, limq_compare_cb_t
Returns:
queue handle if successful, NULL otherwise.
void* limq_dequeue_get ( limq_handle_t  que  ) 

get next queue entry that can be read from. get readable entry from queue without advancing queue pointer. Entry must be released either by limq_dequeue_put() or limq_dequeue_release().

Parameters:
que queue handle.
Returns:
queue_entry if successful, NULL otherwise.
int limq_dequeue_hold ( limq_handle_t  que,
const void *  obj 
)

hold readable queue entry hold readable entry, object must be returned later by limq_dequeue_put() or limq_dequeue_release().

Parameters:
que queue handle.
obj data object pointer returned by limq_dequeue_get().
Returns:
0 if successful, -1 otherwise.
int limq_dequeue_put ( limq_handle_t  que,
const void *  obj 
)

put back readable queue entry release readable queue entry and advance queue pointer if queue object is no longer referenced.

Parameters:
que queue handle.
obj data object pointer returned by limq_dequeue_get().
Returns:
0 if successful and object no longer referenced and queue pointer is advanced. 1 if successful but object is still referenced. -1 otherwise.
int limq_dequeue_release ( limq_handle_t  que,
const void *  obj 
)

release readable queue entry dereference and release queue object, if object is previously held by limq_dequeue_hold(), then also advance queue pointer when hold count goes down to zero.

Parameters:
que queue handle.
obj data object pointer returned by limq_dequeue_get().
Returns:
0 if successful and object no longer referenced and queue pointer is advanced. 1 if successful but object is either still referenced or queue pointer remains not being advanced. -1 otherwise.
void limq_destroy ( limq_handle_t  que  ) 

destroy lim queue.

Parameters:
que queue handle returned by limq_create();
void* limq_enqueue_get ( limq_handle_t  que  ) 

get next queue entry that can be written to.

Parameters:
que queue handle.
Returns:
queue entry if successful, NULL otherwise.
int limq_enqueue_put_ext ( limq_handle_t  que,
const void *  obj,
int  force_top 
)

put back writable queue entry

Parameters:
que queue handle.
obj data object pointer returned by limq_enqueue_get().
force_top if set, entry is forced to be queued to top of the queue.
Returns:
0 if successful and object no longer referenced and queue pointer is advanced. 1 if successful but object is still referenced. -1 otherwise.
int limq_enqueue_release ( limq_handle_t  que,
const void *  obj 
)

release writable queue entry without advance queue pointer next call to limq_enqueue_get() would return the same queue object.

Parameters:
que queue handle.
obj data object pointer returned by limq_enqueue_get().
Returns:
0 if successful and object no longer referenced and queue pointer is advanced. 1 if successful and object is either still referenced or queue pointer remains not being advanced. -1 otherwise.
int limq_entries ( limq_handle_t  que  ) 

query current queue entry number. include entries that either are dequeable or on hold.

Parameters:
que queue handle.
Returns:
current number of queue entries.
int limq_obj_ref_count ( limq_handle_t  que,
const void *  obj 
)

query queue object reference count.

void limq_reset ( limq_handle_t  que  ) 

reset lim queue.

Parameters:
que queue handle returned by limq_create();
int limset_commit ( limset_handle_t  set,
const void *  obj 
)

commit/write object back to set.

Parameters:
set set handle.
obj data object pointer returned by limset_new().
Returns:
0 if successful, -1 otherwise.
int limset_consume ( limset_handle_t  set,
const void *  obj 
)

consume and release readable set entry

Parameters:
set set handle.
obj data object pointer returned by limset_next().
Returns:
0 if successful, -1 otherwise.
limset_handle_t limset_create ( int  entry_bytes,
int  max_entries,
const char *  name 
)

create lim set handle.

Parameters:
entry_bytes bytes of each entry
max_entries maximum allowed set entries
name set name for debug tracking purpose, can be NULL.
Returns:
set handle if successful, NULL otherwise.
void limset_destroy ( limset_handle_t  set  ) 

destroy lim set.

Parameters:
set set handle returned by limset_create();
int limset_entries ( limset_handle_t  set  ) 

query current readable set entry number.

Parameters:
set set handle.
Returns:
current number of readable set entries.
void* limset_new ( limset_handle_t  set  ) 

get next set entry that can be written to.

Parameters:
set set handle.
Returns:
set entry object if successful, NULL otherwise.
void* limset_next ( limset_handle_t  set,
void *  obj 
)

get next set entry that can be read from.

Parameters:
set set handle.
obj current object, fetch next entry from head if NULL.
Returns:
set entry object if successful, NULL otherwise.
static void list_add ( list_t new,
list_t head 
) [inline, static]

add a new entry afer head

Parameters:
new new entry to be added
head list head to add it after
static void list_add_ ( list_t new,
list_t prev,
list_t next 
) [inline, static]
static void list_add_tail ( list_t new,
list_t head 
) [inline, static]

add a new entry before head

Parameters:
new new entry to be added
head list head to add it before
static void list_del ( list_t entry  )  [inline, static]

remove entry from list.

Parameters:
entry the element to delete from the list.
static void list_del_ ( list_t prev,
list_t next 
) [inline, static]
static void list_del_init ( list_t entry  )  [inline, static]

remove entry from list and reinitialize it.

Parameters:
entry the element to delete from the list.
static int list_empty ( const list_t head  )  [inline, static]

test whether a list is empty.

Parameters:
head list head
Returns:
0 if list is not empty, nonzero if it is empty.
static int list_entries ( const list_t head  )  [inline, static]

calculate number of list entries

Parameters:
head list head.
Returns:
number of entries in list.
static void list_init ( list_t list  )  [inline, static]

initialize list.

Parameters:
list list head entry.
LIMOpenMAX Implementation API Reference - Generated by doxygen