qbarray.h File Reference

This is a dynamic array (it can grow, but without moving memory). More...

#include <stdint.h>
#include <unistd.h>
#include <qb/qbdefs.h>

Include dependency graph for qbarray.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	QB_ARRAY_MAX_INDEX_BITS   16
#define	QB_ARRAY_MAX_ELEMENTS   (1 << QB_ARRAY_MAX_INDEX_BITS)

Typedefs
typedef struct qb_array	qb_array_t
	This is an opaque data type representing an instance of an array. More...
typedef void(*	qb_array_new_bin_cb_fn) (qb_array_t *a, uint32_t bin)

Functions
qb_array_t *	qb_array_create (size_t max_elements, size_t element_size)
	Create an array with fixed sized elements. More...
qb_array_t *	qb_array_create_2 (size_t max_elements, size_t element_size, size_t autogrow_elements)
	Create an array with fixed sized elements. More...
int32_t	qb_array_index (qb_array_t *a, int32_t idx, void **element_out)
	Get an element at a particular index. More...
int32_t	qb_array_grow (qb_array_t *a, size_t max_elements)
	Grow the array. More...
size_t	qb_array_num_bins_get (qb_array_t *a)
	Get the number of bins used by the array. More...
size_t	qb_array_elems_per_bin_get (qb_array_t *a)
	Get the number of elements per bin. More...
int32_t	qb_array_new_bin_cb_set (qb_array_t *a, qb_array_new_bin_cb_fn fn)
	Get a callback when a new bin is allocated. More...
void	qb_array_free (qb_array_t *a)
	Free all the memory used by the array. More...

Detailed Description

This is a dynamic array (it can grow, but without moving memory).

arr = qb_array_create_2(64, sizeof(struct my_struct), 256);
...
res = qb_array_index(arr, idx, (void**)&my_ptr);
if (res < 0) {
     return res;
}
// use my_ptr, now even if there is a grow, this pointer will be valid.

Currently, this dynamic array abstract data type can accommodate only 2^QB_ARRAY_MAX_INDEX_BITS elements, and with standard zero-based indexing, this gives a valid index range [0, QB_ARRAY_MAX_ELEMENTS), where the notation denotes the beginning of the interval is included and the end is excluded. In other words, client space shall avoid a pitfall of relying solely on the type of max_elements parameter to qb_array_create and/or of idx parameter to qb_array_index (these types conflict, anyway).

Macro Definition Documentation

QB_ARRAY_MAX_ELEMENTS

#define QB_ARRAY_MAX_ELEMENTS   (1 << QB_ARRAY_MAX_INDEX_BITS)

QB_ARRAY_MAX_INDEX_BITS

#define QB_ARRAY_MAX_INDEX_BITS   16

Typedef Documentation

qb_array_new_bin_cb_fn

typedef void(* qb_array_new_bin_cb_fn) (qb_array_t *a, uint32_t bin)

qb_array_t

typedef struct qb_array qb_array_t

This is an opaque data type representing an instance of an array.

Function Documentation

qb_array_create()

qb_array_t* qb_array_create	(	size_t	max_elements,
		size_t	element_size
	)

Create an array with fixed sized elements.

Parameters

max_elements	initial max elements
element_size	size of each element

Returns

array instance

qb_array_create_2()

qb_array_t* qb_array_create_2	(	size_t	max_elements,
		size_t	element_size,
		size_t	autogrow_elements
	)

Create an array with fixed sized elements.

Parameters

max_elements	initial max elements
element_size	size of each element
autogrow_elements	the number of elements to grow automatically by.

Returns

array instance

Examples

ipcserver.c.

qb_array_elems_per_bin_get()

size_t qb_array_elems_per_bin_get

(

qb_array_t *

a

)

Get the number of elements per bin.

qb_array_free()

void qb_array_free

(

qb_array_t *

a

)

Free all the memory used by the array.

Parameters

a	array instance

qb_array_grow()

int32_t qb_array_grow	(	qb_array_t *	a,
		size_t	max_elements
	)

Grow the array.

Parameters

a	array instance
max_elements	the new maximum size of the array

Returns

(0 == success, else -errno)

qb_array_index()

int32_t qb_array_index	(	qb_array_t *	a,
		int32_t	idx,
		void **	element_out
	)

Get an element at a particular index.

Parameters

a	array instance
idx	the index, valid in [0, QB_ARRAY_MAX_ELEMENTS) range
element_out	the pointer to the element data

Returns

(0 == success, else -errno)

Examples

ipcserver.c.

qb_array_new_bin_cb_set()

int32_t qb_array_new_bin_cb_set	(	qb_array_t *	a,
		qb_array_new_bin_cb_fn	fn
	)

Get a callback when a new bin is allocated.

qb_array_num_bins_get()

size_t qb_array_num_bins_get

(

qb_array_t *

a

)

Get the number of bins used by the array.