qbarray.h(3)

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

SYNOPSIS

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

  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.
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.
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.
int32_t qb_array_index (qb_array_t *a, int32_t idx, void **element_out)
Get an element at a particular index.
int32_t qb_array_grow (qb_array_t *a, size_t max_elements)
Grow the array.
size_t qb_array_num_bins_get (qb_array_t *a)
Get the number of bins used by the array.
size_t qb_array_elems_per_bin_get (qb_array_t *a)
Get the number of elements per bin.
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.
void qb_array_free (qb_array_t *a)
Free all the memory used by the array.

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 parameter to qb_array_create and/or of parameter to qb_array_index (these types conflict, anyway).

Macro Definition Documentation

  #define QB_ARRAY_MAX_ELEMENTS (1 << QB_ARRAY_MAX_INDEX_BITS)

  #define QB_ARRAY_MAX_INDEX_BITS 16

Typedef Documentation

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

  typedef struct qb_array qb_array_t

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

Function Documentation

  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_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

  size_t qb_array_elems_per_bin_get (qb_array_t * a)

Get the number of elements per bin.

  void qb_array_free (qb_array_t * a)

Free all the memory used by the array.

Parameters:
    a array instance

  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)

  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)

  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.

  size_t qb_array_num_bins_get (qb_array_t * a)

Get the number of bins used by the array.

Author

Generated automatically by Doxygen for libqb from the source code.