simclist.h File Reference

#include <inttypes.h>
#include <errno.h>
#include <sys/types.h>

Go to the source code of this file.

Data Structures

struct  list_dump_info_t
struct  list_entry_s
struct  list_attributes_s
struct  list_t

Defines

#define inline
#define restrict

Typedefs

typedef int32_t list_hash_t
typedef int(* element_comparator )(const void *a, const void *b)
typedef int(* element_seeker )(const void *el, const void *indicator)
typedef size_t(* element_meter )(const void *el)
typedef list_hash_t(* element_hash_computer )(const void *el)
typedef void *(* element_serializer )(const void *restrict el, uint32_t *restrict serializ_len)
typedef void *(* element_unserializer )(const void *restrict data, uint32_t *restrict data_len)

Functions

int list_init (list_t *restrict l)
void list_destroy (list_t *restrict l)
int list_attributes_comparator (list_t *restrict l, element_comparator comparator_fun)
int list_attributes_seeker (list_t *restrict l, element_seeker seeker_fun)
int list_attributes_copy (list_t *restrict l, element_meter metric_fun, int copy_data)
int list_attributes_hash_computer (list_t *restrict l, element_hash_computer hash_computer_fun)
int list_attributes_serializer (list_t *restrict l, element_serializer serializer_fun)
int list_attributes_unserializer (list_t *restrict l, element_unserializer unserializer_fun)
int list_append (list_t *restrict l, const void *data)
int list_prepend (list_t *restrict l, const void *restrict data)
void * list_fetch (list_t *restrict l)
void * list_get_at (const list_t *restrict l, unsigned int pos)
void * list_get_max (const list_t *restrict l)
void * list_get_min (const list_t *restrict l)
void * list_extract_at (list_t *restrict l, unsigned int pos)
int list_insert_at (list_t *restrict l, const void *data, unsigned int pos)
int list_delete_at (list_t *restrict l, unsigned int pos)
int list_delete_range (list_t *restrict l, unsigned int posstart, unsigned int posend)
int list_clear (list_t *restrict l)
unsigned int list_size (const list_t *restrict l)
int list_empty (const list_t *restrict l)
int list_locate (const list_t *restrict l, const void *data)
void * list_seek (list_t *restrict l, const void *indicator)
int list_contains (const list_t *restrict l, const void *data)
int list_concat (const list_t *l1, const list_t *l2, list_t *restrict dest)
int list_sort (list_t *restrict l, int versus)
int list_iterator_start (list_t *restrict l)
void * list_iterator_next (list_t *restrict l)
int list_iterator_hasnext (const list_t *restrict l)
int list_iterator_stop (list_t *restrict l)
int list_hash (const list_t *restrict l, list_hash_t *restrict hash)
int list_dump_getinfo_filedescriptor (int fd, list_dump_info_t *restrict info)
int list_dump_getinfo_file (const char *restrict filename, list_dump_info_t *restrict info)
int list_dump_filedescriptor (const list_t *restrict l, int fd, size_t *restrict len)
int list_dump_file (const list_t *restrict l, const char *restrict filename, size_t *restrict len)
int list_restore_filedescriptor (list_t *restrict l, int fd, size_t *restrict len)
int list_restore_file (list_t *restrict l, const char *restrict filename, size_t *len)
int list_comparator_int8_t (const void *a, const void *b)
int list_comparator_int16_t (const void *a, const void *b)
int list_comparator_int32_t (const void *a, const void *b)
int list_comparator_int64_t (const void *a, const void *b)
int list_comparator_uint8_t (const void *a, const void *b)
int list_comparator_uint16_t (const void *a, const void *b)
int list_comparator_uint32_t (const void *a, const void *b)
int list_comparator_uint64_t (const void *a, const void *b)
int list_comparator_float (const void *a, const void *b)
int list_comparator_double (const void *a, const void *b)
int list_comparator_string (const void *a, const void *b)
size_t list_meter_int8_t (const void *el)
size_t list_meter_int16_t (const void *el)
size_t list_meter_int32_t (const void *el)
size_t list_meter_int64_t (const void *el)
size_t list_meter_uint8_t (const void *el)
size_t list_meter_uint16_t (const void *el)
size_t list_meter_uint32_t (const void *el)
size_t list_meter_uint64_t (const void *el)
size_t list_meter_float (const void *el)
size_t list_meter_double (const void *el)
size_t list_meter_string (const void *el)
list_hash_t list_hashcomputer_int8_t (const void *el)
list_hash_t list_hashcomputer_int16_t (const void *el)
list_hash_t list_hashcomputer_int32_t (const void *el)
list_hash_t list_hashcomputer_int64_t (const void *el)
list_hash_t list_hashcomputer_uint8_t (const void *el)
list_hash_t list_hashcomputer_uint16_t (const void *el)
list_hash_t list_hashcomputer_uint32_t (const void *el)
list_hash_t list_hashcomputer_uint64_t (const void *el)
list_hash_t list_hashcomputer_float (const void *el)
list_hash_t list_hashcomputer_double (const void *el)
list_hash_t list_hashcomputer_string (const void *el)


Define Documentation

#define inline

#define restrict


Typedef Documentation

typedef int(* element_comparator)(const void *a, const void *b)

a comparator of elements.

A comparator of elements is a function that:

  1. receives two references to elements a and b
  2. returns {<0, 0, >0} if (a > b), (a == b), (a < b) respectively

It is responsability of the function to handle possible NULL values.

typedef list_hash_t(* element_hash_computer)(const void *el)

a function computing the hash of elements.

An hash computing function is a function that:

  1. receives the reference to an element el
  2. returns a hash value for el

It is responsability of the function to handle possible NULL values.

typedef size_t(* element_meter)(const void *el)

an element lenght meter.

An element meter is a function that:

  1. receives the reference to an element el
  2. returns its size in bytes

It is responsability of the function to handle possible NULL values.

typedef int(* element_seeker)(const void *el, const void *indicator)

a seeker of elements.

An element seeker is a function that:

  1. receives a reference to an element el
  2. receives a reference to some indicator data
  3. returns non-0 if the element matches the indicator, 0 otherwise

It is responsability of the function to handle possible NULL values in any argument.

typedef void*(* element_serializer)(const void *restrict el, uint32_t *restrict serializ_len)

a function for serializing an element.

A serializer function is one that gets a reference to an element, and returns a reference to a buffer that contains its serialization along with the length of this buffer. It is responsability of the function to handle possible NULL values, returning a NULL buffer and a 0 buffer length.

These functions have 3 goals:

  1. "freeze" and "flatten" the memory representation of the element
  2. provide a portable (wrt byte order, or type size) representation of the element, if the dump can be used on different sw/hw combinations
  3. possibly extract a compressed representation of the element

Parameters:
el reference to the element data
serialize_buffer reference to fill with the length of the buffer
Returns:
reference to the buffer with the serialized data

typedef void*(* element_unserializer)(const void *restrict data, uint32_t *restrict data_len)

a function for un-serializing an element.

An unserializer function accomplishes the inverse operation of the serializer function. An unserializer function is one that gets a serialized representation of an element and turns it backe to the original element. The serialized representation is passed as a reference to a buffer with its data, and the function allocates and returns the buffer containing the original element, and it sets the length of this buffer into the integer passed by reference.

Parameters:
data reference to the buffer with the serialized representation of the element
data_len reference to the location where to store the length of the data in the buffer returned
Returns:
reference to a buffer with the original, unserialized representation of the element

typedef int32_t list_hash_t

Type representing list hashes.

This is a signed integer value.


Function Documentation

int list_append ( list_t *restrict  l,
const void *  data 
)

append data at the end of the list.

This function is useful for adding elements with a FIFO/queue policy.

Parameters:
l list to operate
data pointer to user data to append
Returns:
1 for success. < 0 for failure

References list_insert_at().

Referenced by list_restore_filedescriptor().

int list_attributes_comparator ( list_t *restrict  l,
element_comparator  comparator_fun 
)

set the comparator function for list elements.

Comparator functions are used for searching and sorting. If NULL is passed as reference to the function, the comparator is disabled.

Parameters:
l list to operate
comparator_fun pointer to the actual comparator function
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_comparator()

int list_attributes_copy ( list_t *restrict  l,
element_meter  metric_fun,
int  copy_data 
)

require to free element data when list entry is removed (default: don't free).

[ advanced preference ]

By default, when an element is removed from the list, it disappears from the list by its actual data is not free()d. With this option, every deletion causes element data to be freed.

It is responsability of this function to correctly handle NULL values, if NULL elements are inserted into the list.

Parameters:
l list to operate
metric_fun pointer to the actual metric function
copy_data 0: do not free element data (default); non-0: do free
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_meter()

list_meter_int8_t()

list_meter_int16_t()

list_meter_int32_t()

list_meter_int64_t()

list_meter_uint8_t()

list_meter_uint16_t()

list_meter_uint32_t()

list_meter_uint64_t()

list_meter_float()

list_meter_double()

list_meter_string()

int list_attributes_hash_computer ( list_t *restrict  l,
element_hash_computer  hash_computer_fun 
)

set the element hash computing function for the list elements.

[ advanced preference ]

An hash can be requested depicting the list status at a given time. An hash only depends on the elements and their order. By default, the hash of an element is only computed on its reference. With this function, the user can set a custom function computing the hash of an element. If such function is provided, the list_hash() function automatically computes the list hash using the custom function instead of simply referring to element references.

Parameters:
l list to operate
hash_computer_fun pointer to the actual hash computing function
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_hash_computer()

int list_attributes_seeker ( list_t *restrict  l,
element_seeker  seeker_fun 
)

set a seeker function for list elements.

Seeker functions are used for finding elements. If NULL is passed as reference to the function, the seeker is disabled.

Parameters:
l list to operate
seeker_fun pointer to the actual seeker function
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_seeker()

int list_attributes_serializer ( list_t *restrict  l,
element_serializer  serializer_fun 
)

set the element serializer function for the list elements.

[ advanced preference ]

Serialize functions are used for dumping the list to some persistent storage. The serializer function is called for each element; it is passed a reference to the element and a reference to a size_t object. It will provide (and return) the buffer with the serialization of the element and fill the size_t object with the length of this serialization data.

Parameters:
l list to operate
serializer_fun pointer to the actual serializer function
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_serializer()

list_dump_filedescriptor()

list_restore_filedescriptor()

int list_attributes_unserializer ( list_t *restrict  l,
element_unserializer  unserializer_fun 
)

set the element unserializer function for the list elements.

[ advanced preference ]

Unserialize functions are used for restoring the list from some persistent storage. The unserializer function is called for each element segment read from the storage; it is passed the segment and a reference to an integer. It shall allocate and return a buffer compiled with the resumed memory representation of the element, and set the integer value to the length of this buffer.

Parameters:
l list to operate
unserializer_fun pointer to the actual unserializer function
Returns:
0 if the attribute was successfully set; -1 otherwise
See also:
element_unserializer()

list_dump_filedescriptor()

list_restore_filedescriptor()

int list_clear ( list_t *restrict  l  ) 

clear all the elements off of the list.

The element datums will not be freed.

See also:
list_delete_range()

list_size()

Parameters:
l list to operate
Returns:
the number of elements in the list before cleaning

References list_entry_s::data, list_entry_s::next, list_entry_s::prev, and SIMCLIST_MAX_SPARE_ELEMS.

Referenced by list_destroy().

int list_comparator_double ( const void *  a,
const void *  b 
)

ready-made comparator for double elements.

See also:
list_attributes_comparator()

int list_comparator_float ( const void *  a,
const void *  b 
)

ready-made comparator for float elements.

See also:
list_attributes_comparator()

int list_comparator_int16_t ( const void *  a,
const void *  b 
)

ready-made comparator for int16_t elements.

See also:
list_attributes_comparator()

int list_comparator_int32_t ( const void *  a,
const void *  b 
)

ready-made comparator for int32_t elements.

See also:
list_attributes_comparator()

int list_comparator_int64_t ( const void *  a,
const void *  b 
)

ready-made comparator for int64_t elements.

See also:
list_attributes_comparator()

int list_comparator_int8_t ( const void *  a,
const void *  b 
)

ready-made comparator for int8_t elements.

See also:
list_attributes_comparator()

int list_comparator_string ( const void *  a,
const void *  b 
)

ready-made comparator for string elements.

See also:
list_attributes_comparator()

int list_comparator_uint16_t ( const void *  a,
const void *  b 
)

ready-made comparator for uint16_t elements.

See also:
list_attributes_comparator()

int list_comparator_uint32_t ( const void *  a,
const void *  b 
)

ready-made comparator for uint32_t elements.

See also:
list_attributes_comparator()

int list_comparator_uint64_t ( const void *  a,
const void *  b 
)

ready-made comparator for uint64_t elements.

See also:
list_attributes_comparator()

int list_comparator_uint8_t ( const void *  a,
const void *  b 
)

ready-made comparator for uint8_t elements.

See also:
list_attributes_comparator()

int list_concat ( const list_t l1,
const list_t l2,
list_t *restrict  dest 
)

concatenate two lists

Concatenates one list with another, and stores the result into a user-provided list object, which must be different from both the lists to concatenate. Attributes from the original lists are not cloned. The destination list referred is threated as virgin room: if it is an existing list containing elements, memory leaks will happen. It is OK to specify the same list twice as source, for "doubling" it in the destination.

Parameters:
l1 base list
l2 list to append to the base
dest reference to the destination list
Returns:
0 for success, -1 for errors

References list_entry_s::data, list_t::head_sentinel, list_init(), list_entry_s::next, list_t::numels, list_entry_s::prev, and list_t::tail_sentinel.

int list_contains ( const list_t *restrict  l,
const void *  data 
)

inspect whether some data is member of the list.

Warning:
Requires a comparator function to be set for the list.
By default, a per-reference comparison is accomplished. That is, the data is in list if any element of the list points to the same location of data. A "semantic" comparison is accomplished, otherwise, if a comparator function has been set previously, with list_attributes_comparator(); in which case, the given data reference is believed to be in list iff comparator_fun(elementdata, userdata) == 0 for any element in the list.

Parameters:
l list to operate
data reference to the data to search
Returns:
0 iff the list does not contain data as an element
See also:
list_attributes_comparator()

References list_locate().

int list_delete_at ( list_t *restrict  l,
unsigned int  pos 
)

expunge an element at a given position from the list.

Parameters:
l list to operate
pos [0,size-1] position index of the element to be deleted
Returns:
0 on success. Negative value on failure

int list_delete_range ( list_t *restrict  l,
unsigned int  posstart,
unsigned int  posend 
)

expunge an array of elements from the list, given their position range.

Parameters:
l list to operate
posstart [0,size-1] position index of the first element to be deleted
posend [posstart,size-1] position of the last element to be deleted
Returns:
the number of elements successfully removed

References list_entry_s::data, list_entry_s::next, list_entry_s::prev, and SIMCLIST_MAX_SPARE_ELEMS.

void list_destroy ( list_t *restrict  l  ) 

completely remove the list from memory.

This function is the inverse of list_init(). It is meant to be called when the list is no longer going to be used. Elements and possible memory taken for internal use are freed.

Parameters:
l list to destroy

References list_clear().

int list_dump_file ( const list_t *restrict  l,
const char *restrict  filename,
size_t *restrict  len 
)

dump the list to a file name.

This function creates a filename and dumps the current content of the list to it. If the file exists it is overwritten. The number of bytes written to the file can be returned in a specified argument.

Parameters:
l list to operate
filename filename to write to
len location to store the resulting length of the dump (bytes), or NULL
Returns:
0 if successful; -1 otherwise
See also:
list_attributes_copy()

element_serializer()

list_attributes_serializer()

list_dump_filedescriptor()

list_restore_file()

This function stores a representation of the list

References list_dump_filedescriptor().

int list_dump_filedescriptor ( const list_t *restrict  l,
int  fd,
size_t *restrict  len 
)

dump the list into an open, writable file descriptor.

This function "dumps" the list to a persistent storage so it can be preserved across process terminations. When called, the file descriptor must be open for writing and positioned where the serialized data must begin. It writes its serialization of the list in a form which is portable across different architectures. Dump can be safely performed on stream-only (non seekable) descriptors. The file descriptor is not closed at the end of the operations.

To use dump functions, either of these conditions must be satisfied:

  1. a metric function has been specified with list_attributes_copy()
  2. a serializer function has been specified with list_attributes_serializer()

If a metric function has been specified, each element of the list is dumped as-is from memory, copying it from its pointer for its length down to the file descriptor. This might have impacts on portability of the dump to different architectures.

If a serializer function has been specified, its result for each element is dumped to the file descriptor.

Parameters:
l list to operate
fd file descriptor to write to
len location to store the resulting length of the dump (bytes), or NULL
Returns:
0 if successful; -1 otherwise
See also:
element_serializer()

list_attributes_copy()

list_attributes_serializer()

References list_entry_s::data, list_dump_header_s::elemlen, hton64, list_hash(), list_dump_header_s::listhash, list_entry_s::next, list_dump_header_s::numels, random, list_dump_header_s::rndterm, SIMCLIST_DUMPFORMAT_HEADERLEN, SIMCLIST_DUMPFORMAT_VERSION, list_dump_header_s::timestamp, list_dump_header_s::totlistlen, list_dump_header_s::ver, and WRITE_ERRCHECK.

Referenced by list_dump_file().

int list_dump_getinfo_file ( const char *restrict  filename,
list_dump_info_t *restrict  info 
)

get meta informations on a list dump on file.

[ advanced function ]

Extracts the meta information from a SimCList dump located in a file.

Parameters:
filename filename of the file to fetch from
info reference to a dump metainformation structure to fill
Returns:
0 for success; <0 for failure
See also:
list_dump_filedescriptor()

References list_dump_getinfo_filedescriptor().

int list_dump_getinfo_filedescriptor ( int  fd,
list_dump_info_t *restrict  info 
)

get meta informations on a list dump on filedescriptor.

[ advanced function ]

Extracts the meta information from a SimCList dump located in a file descriptor. The file descriptor must be open and positioned at the beginning of the SimCList dump block.

Parameters:
fd file descriptor to get metadata from
info reference to a dump metainformation structure to fill
Returns:
0 for success; <0 for failure
See also:
list_dump_filedescriptor()

References hton64, READ_ERRCHECK, and SIMCLIST_DUMPFORMAT_VERSION.

Referenced by list_dump_getinfo_file().

int list_empty ( const list_t *restrict  l  ) 

inspect whether the list is empty.

Parameters:
l list to operate
Returns:
0 iff the list is not empty
See also:
list_size()

void* list_extract_at ( list_t *restrict  l,
unsigned int  pos 
)

retrieve and remove from list an element at a given position.

Parameters:
l list to operate
pos [0,size-1] position index of the element wanted
Returns:
reference to user datum, or NULL on errors

References list_entry_s::data.

Referenced by list_fetch().

void* list_fetch ( list_t *restrict  l  ) 

extract the element in the top of the list.

This function is for using a list with a FIFO/queue policy.

Parameters:
l list to operate
Returns:
reference to user datum, or NULL on errors

References list_extract_at().

void* list_get_at ( const list_t *restrict  l,
unsigned int  pos 
)

retrieve an element at a given position.

Parameters:
l list to operate
pos [0,size-1] position index of the element wanted
Returns:
reference to user datum, or NULL on errors

References list_entry_s::data.

void* list_get_max ( const list_t *restrict  l  ) 

return the maximum element of the list.

Warning:
Requires a comparator function to be set for the list.
Returns the maximum element with respect to the comparator function output.

See also:
list_attributes_comparator()
Parameters:
l list to operate
Returns:
the reference to the element, or NULL

void* list_get_min ( const list_t *restrict  l  ) 

return the minimum element of the list.

Warning:
Requires a comparator function to be set for the list.
Returns the minimum element with respect to the comparator function output.

See also:
list_attributes_comparator()
Parameters:
l list to operate
Returns:
the reference to the element, or NULL

int list_hash ( const list_t *restrict  l,
list_hash_t *restrict  hash 
)

return the hash of the current status of the list.

Parameters:
l list to operate
hash where the resulting hash is put
Returns:
0 for success; <0 for failure

References list_entry_s::data, and list_entry_s::next.

Referenced by list_dump_filedescriptor().

list_hash_t list_hashcomputer_double ( const void *  el  ) 

ready-made hash function for double elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_float ( const void *  el  ) 

ready-made hash function for float elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_int16_t ( const void *  el  ) 

ready-made hash function for int16_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_int32_t ( const void *  el  ) 

ready-made hash function for int32_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_int64_t ( const void *  el  ) 

ready-made hash function for int64_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_int8_t ( const void *  el  ) 

ready-made hash function for int8_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_string ( const void *  el  ) 

ready-made hash function for string elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_uint16_t ( const void *  el  ) 

ready-made hash function for uint16_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_uint32_t ( const void *  el  ) 

ready-made hash function for uint32_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_uint64_t ( const void *  el  ) 

ready-made hash function for uint64_t elements.

See also:
list_attributes_hash_computer()

list_hash_t list_hashcomputer_uint8_t ( const void *  el  ) 

ready-made hash function for uint8_t elements.

See also:
list_attributes_hash_computer()

int list_init ( list_t *restrict  l  ) 

initialize a list object for use.

Parameters:
l must point to a user-provided memory location
Returns:
0 for success. -1 for failure

References SIMCLIST_MAX_SPARE_ELEMS, and srandom.

Referenced by list_concat().

int list_insert_at ( list_t *restrict  l,
const void *  data,
unsigned int  pos 
)

insert an element at a given position.

Parameters:
l list to operate
data reference to data to be inserted
pos [0,size-1] position index to insert the element at
Returns:
positive value on success. Negative on failure

References list_entry_s::data, list_entry_s::next, and list_entry_s::prev.

Referenced by list_append(), and list_prepend().

int list_iterator_hasnext ( const list_t *restrict  l  ) 

inspect whether more elements are available in the iteration session.

Parameters:
l list to operate
Returns:
0 iff no more elements are available.

void* list_iterator_next ( list_t *restrict  l  ) 

return the next element in the iteration session.

Parameters:
l list to operate
Returns:
element datum, or NULL on errors

int list_iterator_start ( list_t *restrict  l  ) 

start an iteration session.

This function prepares the list to be iterated.

Parameters:
l list to operate
Returns:
0 if the list cannot be currently iterated. >0 otherwise
See also:
list_iterator_stop()

int list_iterator_stop ( list_t *restrict  l  ) 

end an iteration session.

Parameters:
l list to operate
Returns:
0 iff the iteration session cannot be stopped

int list_locate ( const list_t *restrict  l,
const void *  data 
)

find the position of an element in a list.

Warning:
Requires a comparator function to be set for the list.
Inspects the given list looking for the given element; if the element is found, its position into the list is returned. Elements are inspected comparing references if a comparator has not been set. Otherwise, the comparator is used to find the element.

Parameters:
l list to operate
data reference of the element to search for
Returns:
position of element in the list, or <0 if not found
See also:
list_attributes_comparator()

list_get_at()

References list_entry_s::data, and list_entry_s::next.

Referenced by list_contains().

size_t list_meter_double ( const void *  el  ) 

ready-made metric function for double elements.

See also:
list_attributes_copy()

size_t list_meter_float ( const void *  el  ) 

ready-made metric function for float elements.

See also:
list_attributes_copy()

size_t list_meter_int16_t ( const void *  el  ) 

ready-made metric function for int16_t elements.

See also:
list_attributes_copy()

size_t list_meter_int32_t ( const void *  el  ) 

ready-made metric function for int32_t elements.

See also:
list_attributes_copy()

size_t list_meter_int64_t ( const void *  el  ) 

ready-made metric function for int64_t elements.

See also:
list_attributes_copy()

size_t list_meter_int8_t ( const void *  el  ) 

ready-made metric function for int8_t elements.

See also:
list_attributes_copy()

size_t list_meter_string ( const void *  el  ) 

ready-made metric function for string elements.

See also:
list_attributes_copy()

size_t list_meter_uint16_t ( const void *  el  ) 

ready-made metric function for uint16_t elements.

See also:
list_attributes_copy()

size_t list_meter_uint32_t ( const void *  el  ) 

ready-made metric function for uint32_t elements.

See also:
list_attributes_copy()

size_t list_meter_uint64_t ( const void *  el  ) 

ready-made metric function for uint64_t elements.

See also:
list_attributes_copy()

size_t list_meter_uint8_t ( const void *  el  ) 

ready-made metric function for uint8_t elements.

See also:
list_attributes_copy()

int list_prepend ( list_t *restrict  l,
const void *restrict  data 
)

insert data in the head of the list.

This function is useful for adding elements with a LIFO/Stack policy.

Parameters:
l list to operate
data pointer to user data to append
Returns:
1 for success. < 0 for failure

int list_restore_file ( list_t *restrict  l,
const char *restrict  filename,
size_t *  len 
)

restore the list from a file name.

This function restores the content of a list from a file into memory. It is the inverse of list_dump_file().

See also:
element_unserializer()

list_attributes_unserializer()

list_dump_file()

list_restore_filedescriptor()

Parameters:
l list to restore to
filename filename to read data from
len location to store the length of the dump read (bytes), or NULL
Returns:
0 if successful; -1 otherwise

int list_restore_filedescriptor ( list_t *restrict  l,
int  fd,
size_t *restrict  len 
)

restore the list from an open, readable file descriptor to memory.

This function is the "inverse" of list_dump_filedescriptor(). It restores the list content from a (open, read-ready) file descriptor to memory. An unserializer might be needed to restore elements from the persistent representation back into memory-consistent format. List attributes can not be restored and must be set manually.

See also:
list_dump_filedescriptor()

list_attributes_serializer()

list_attributes_unserializer()

Parameters:
l list to restore to
fd file descriptor to read from.
len location to store the length of the dump read (bytes), or NULL
Returns:
0 if successful; -1 otherwise

References list_dump_header_s::elemlen, EPROTO, list_append(), list_dump_header_s::listhash, list_dump_header_s::numels, READ_ERRCHECK, list_dump_header_s::rndterm, SIMCLIST_DUMPFORMAT_VERSION, list_dump_header_s::timestamp, list_dump_header_s::totlistlen, and list_dump_header_s::ver.

Referenced by list_restore_file().

void* list_seek ( list_t *restrict  l,
const void *  indicator 
)

returns an element given an indicator.

Warning:
Requires a seeker function to be set for the list.
Inspect the given list looking with the seeker if an element matches an indicator. If such element is found, the reference to the element is returned.

Parameters:
l list to operate
indicator indicator data to pass to the seeker along with elements
Returns:
reference to the element accepted by the seeker, or NULL if none found

References list_entry_s::data, and list_entry_s::next.

unsigned int list_size ( const list_t *restrict  l  ) 

inspect the number of elements in the list.

Parameters:
l list to operate
Returns:
number of elements currently held by the list

int list_sort ( list_t *restrict  l,
int  versus 
)

sort list elements.

Warning:
Requires a comparator function to be set for the list.
Sorts the list in ascending or descending order as specified by the versus flag. The algorithm chooses autonomously what algorithm is best suited for sorting the list wrt its current status.

Parameters:
l list to operate
versus positive: order small to big; negative: order big to small
Returns:
0: sorting went OK non-0: errors happened
See also:
list_attributes_comparator()


Generated on Wed Aug 12 21:19:36 2009 for SimCList by  doxygen 1.5.9