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()