CLIB vectors are ubiquitous dynamically resized arrays with by user defined "headers". More...

Include dependency graph for vec.h:

Macros
#define	vec_resize_has(V, N, H, A, S)
	Resize a vector (general version). More...

#define	vec_resize_ha(V, N, H, A) vec_resize_has(V,N,H,A,VEC_NUMA_UNSPECIFIED)
	Resize a vector (less general version). More...

#define	vec_resize(V, N) vec_resize_ha(V,N,0,0)
	Resize a vector (no header, unspecified alignment) Add N elements to end of given vector V, return pointer to start of vector. More...

#define	vec_resize_aligned(V, N, A) vec_resize_ha(V,N,0,A)
	Resize a vector (no header, alignment specified). More...

#define	vec_alloc_ha(V, N, H, A)
	Allocate space for N more elements. More...

#define	vec_alloc(V, N) vec_alloc_ha(V,N,0,0)
	Allocate space for N more elements (no header, unspecified alignment) More...

#define	vec_alloc_aligned(V, N, A) vec_alloc_ha(V,N,0,A)
	Allocate space for N more elements (no header, given alignment) More...

#define	vec_new_ha(T, N, H, A)
	Create new vector of given type and length (general version). More...

#define	vec_new(T, N) vec_new_ha(T,N,0,0)
	Create new vector of given type and length (unspecified alignment, no header). More...

#define	vec_new_aligned(T, N, A) vec_new_ha(T,N,0,A)
	Create new vector of given type and length (alignment specified, no header). More...

#define	vec_free_h(V, H)
	Free vector's memory (general version) More...

#define	vec_free(V) vec_free_h(V,0)
	Free vector's memory (no header). More...

#define	vec_free_header(h) clib_mem_free (h)
	Free vector user header (syntactic sugar) More...

#define	vec_dup_ha_numa(V, H, A, S)
	Return copy of vector (general version). More...

#define	vec_dup_ha(V, H, A) vec_dup_ha_numa(V,H,A,VEC_NUMA_UNSPECIFIED)
	Return copy of vector (VEC_NUMA_UNSPECIFIED). More...

#define	vec_dup(V) vec_dup_ha(V,0,0)
	Return copy of vector (no header, no alignment) More...

#define	vec_dup_aligned(V, A) vec_dup_ha(V,0,A)
	Return copy of vector (no header, alignment specified). More...

#define	vec_copy(DST, SRC)
	Copy a vector, memcpy wrapper. More...

#define	vec_clone(NEW_V, OLD_V)
	Clone a vector. More...

#define	vec_validate_han(V, I, H, A, N)
	Make sure vector is long enough for given index (general version). More...

#define	vec_validate_ha(V, I, H, A) vec_validate_han(V,I,H,A,VEC_NUMA_UNSPECIFIED)

#define	vec_validate(V, I) vec_validate_ha(V,I,0,0)
	Make sure vector is long enough for given index (no header, unspecified alignment) More...

#define	vec_validate_aligned(V, I, A) vec_validate_ha(V,I,0,A)
	Make sure vector is long enough for given index (no header, specified alignment) More...

#define	vec_validate_init_empty_ha(V, I, INIT, H, A)
	Make sure vector is long enough for given index and initialize empty space (general version) More...

#define	vec_validate_init_empty(V, I, INIT) vec_validate_init_empty_ha(V,I,INIT,0,0)
	Make sure vector is long enough for given index and initialize empty space (no header, unspecified alignment) More...

#define	vec_validate_init_empty_aligned(V, I, INIT, A) vec_validate_init_empty_ha(V,I,INIT,0,A)
	Make sure vector is long enough for given index and initialize empty space (no header, alignment alignment) More...

#define	vec_add1_ha(V, E, H, A)
	Add 1 element to end of vector (general version). More...

#define	vec_add1(V, E) vec_add1_ha(V,E,0,0)
	Add 1 element to end of vector (unspecified alignment). More...

#define	vec_add1_aligned(V, E, A) vec_add1_ha(V,E,0,A)
	Add 1 element to end of vector (alignment specified). More...

#define	vec_add2_ha(V, P, N, H, A)
	Add N elements to end of vector V, return pointer to new elements in P. More...

#define	vec_add2(V, P, N) vec_add2_ha(V,P,N,0,0)
	Add N elements to end of vector V, return pointer to new elements in P. More...

#define	vec_add2_aligned(V, P, N, A) vec_add2_ha(V,P,N,0,A)
	Add N elements to end of vector V, return pointer to new elements in P. More...

#define	vec_add_ha(V, E, N, H, A)
	Add N elements to end of vector V (general version) More...

#define	vec_add(V, E, N) vec_add_ha(V,E,N,0,0)
	Add N elements to end of vector V (no header, unspecified alignment) More...

#define	vec_add_aligned(V, E, N, A) vec_add_ha(V,E,N,0,A)
	Add N elements to end of vector V (no header, specified alignment) More...

#define	vec_pop(V)
	Returns last element of a vector and decrements its length. More...

#define	vec_pop2(V, E)
	Set E to the last element of a vector, decrement vector length. More...

#define	vec_insert_init_empty_ha(V, N, M, INIT, H, A)
	Insert N vector elements starting at element M, initialize new elements (general version). More...

#define	vec_insert_ha(V, N, M, H, A) vec_insert_init_empty_ha(V,N,M,0,H,A)
	Insert N vector elements starting at element M, initialize new elements to zero (general version) More...

#define	vec_insert(V, N, M) vec_insert_ha(V,N,M,0,0)
	Insert N vector elements starting at element M, initialize new elements to zero (no header, unspecified alignment) More...

#define	vec_insert_aligned(V, N, M, A) vec_insert_ha(V,N,M,0,A)
	Insert N vector elements starting at element M, initialize new elements to zero (no header, alignment specified) More...

#define	vec_insert_init_empty(V, N, M, INIT) vec_insert_init_empty_ha(V,N,M,INIT,0,0)
	Insert N vector elements starting at element M, initialize new elements (no header, unspecified alignment) More...

#define	vec_insert_init_empty_aligned(V, N, M, INIT, A) vec_insert_init_empty_ha(V,N,M,INIT,0,A)
	Insert N vector elements starting at element M, initialize new elements (no header, specified alignment) More...

#define	vec_insert_elts_ha(V, E, N, M, H, A)
	Insert N vector elements starting at element M, insert given elements (general version) More...

#define	vec_insert_elts(V, E, N, M) vec_insert_elts_ha(V,E,N,M,0,0)
	Insert N vector elements starting at element M, insert given elements (no header, unspecified alignment) More...

#define	vec_insert_elts_aligned(V, E, N, M, A) vec_insert_elts_ha(V,E,N,M,0,A)
	Insert N vector elements starting at element M, insert given elements (no header, specified alignment) More...

#define	vec_delete(V, N, M)
	Delete N elements starting at element M. More...

#define	vec_del1(v, i)
	Delete the element at index I. More...

#define	vec_append(v1, v2)
	Append v2 after v1. More...

#define	vec_append_aligned(v1, v2, align)
	Append v2 after v1. More...

#define	vec_prepend(v1, v2)
	Prepend v2 before v1. More...

#define	vec_prepend_aligned(v1, v2, align)
	Prepend v2 before v1. More...

#define	vec_zero(var)
	Zero all vector elements. More...

#define	vec_set(v, val)
	Set all vector elements to given value. More...

#define	vec_is_equal(v1, v2) (vec_len (v1) == vec_len (v2) && ! memcmp ((v1), (v2), vec_len (v1) * sizeof ((v1)[0])))
	Compare two vectors, not NULL-pointer tolerant. More...

#define	vec_cmp(v1, v2)
	Compare two vectors (only applicable to vectors of signed numbers). More...

#define	vec_search(v, E)
	Search a vector for the index of the entry that matches. More...

#define	vec_search_with_function(v, E, fn)
	Search a vector for the index of the entry that matches. More...

#define	vec_sort_with_function(vec, f)
	Sort a vector using the supplied element comparison function. More...

#define	vec_validate_init_c_string(V, S, L)
	Make a vector containing a NULL terminated c-string. More...

#define	vec_c_string_is_terminated(V) (((V) != 0) && (vec_len (V) != 0) && ((V)[vec_len ((V)) - 1] == 0))
	Test whether a vector is a NULL terminated c-string. More...

#define	vec_terminate_c_string(V)
	(If necessary) NULL terminate a vector containing a c-string. More...

Functions
void *	vec_resize_allocate_memory (void *v, word length_increment, uword data_bytes, uword header_bytes, uword data_align, uword numa_id)
	Low-level resize allocation function, usually not called directly. More...

uword	clib_mem_is_vec_h (void *v, uword header_bytes)
	Predicate function, says whether the supplied vector is a clib heap object (general version). More...

static uword	clib_mem_is_vec (void *v)
	Predicate function, says whether the supplied vector is a clib heap object. More...

void	vec_free_not_inline (void *v)

Detailed Description

CLIB vectors are ubiquitous dynamically resized arrays with by user defined "headers".

Many CLIB data structures (e.g. hash, heap, pool) are vectors with various different headers.

The memory layout looks like this:

                 user header (aligned to uword boundary)
                 vector length: number of elements
user's pointer-> vector element #0
                 vector element #1
                 ...

The user pointer contains the address of vector element # 0. Null pointer vectors are valid and mean a zero length vector.

You can reset the length of an allocated vector to zero via the vec_reset_length(v) macro, or by setting the vector length field to zero (e.g. _vec_len (v) = 0). Vec_reset_length(v) preferred: it understands Null pointers.

Typically, the header is not present. Headers allow for other data structures to be built atop CLIB vectors.

Users may specify the alignment for first data element of a vector via the vec_*_aligned macros.

Vector elements can be any C type e.g. (int, double, struct bar). This is also true for data types built atop vectors (e.g. heap, pool, etc.).

Many macros have _a variants supporting alignment of vector elements and _h variants supporting non-zero-length vector headers. The _ha variants support both. Additionally cacheline alignment within a vector element structure can be specified using the CLIB_CACHE_LINE_ALIGN_MARK() macro.

Standard programming error: memorize a pointer to the ith element of a vector then expand it. Vectors expand by 3/2, so such code may appear to work for a period of time. Memorize vector indices which are invariant.

Definition in file vec.h.

Macro Definition Documentation

◆ vec_add

#define vec_add	(	V,
		E,
		N
	)	vec_add_ha(V,E,N,0,0)

Add N elements to end of vector V (no header, unspecified alignment)

Parameters

V	pointer to a vector
E	pointer to element(s) to add
N	number of elements to add

Returns: V (value-result macro parameter)

Definition at line 668 of file vec.h.

◆ vec_add1

#define vec_add1	(	V,
		E
	)	vec_add1_ha(V,E,0,0)

Add 1 element to end of vector (unspecified alignment).

Parameters

V	pointer to a vector
E	element to add

Returns: V (value-result macro parameter)

Definition at line 592 of file vec.h.

◆ vec_add1_aligned

#define vec_add1_aligned	(	V,
		E,
		A
	)	vec_add1_ha(V,E,0,A)

Add 1 element to end of vector (alignment specified).

Parameters

V	pointer to a vector
E	element to add
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 601 of file vec.h.

◆ vec_add1_ha

#define vec_add1_ha	(	V,
		E,
		H,
		A
	)

Value:

do {                                                                    \
  word _v(l) = vec_len (V);                                             \
  V = _vec_resize ((V), 1, (_v(l) + 1) * sizeof ((V)[0]), (H), (A));    \
  (V)[_v(l)] = (E);                                                     \
} while (0)

Add 1 element to end of vector (general version).

Parameters

V	pointer to a vector
E	element to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 579 of file vec.h.

◆ vec_add2

#define vec_add2	(	V,
		P,
		N
	)	vec_add2_ha(V,P,N,0,0)

Add N elements to end of vector V, return pointer to new elements in P.

(no header, unspecified alignment)

Parameters

V	pointer to a vector
P	pointer to new vector element(s)
N	number of elements to add

Returns: V and P (value-result macro parameters)

Definition at line 630 of file vec.h.

◆ vec_add2_aligned

#define vec_add2_aligned	(	V,
		P,
		N,
		A
	)	vec_add2_ha(V,P,N,0,A)

Add N elements to end of vector V, return pointer to new elements in P.

(no header, alignment specified)

Parameters

V	pointer to a vector
P	pointer to new vector element(s)
N	number of elements to add
A	alignment (may be zero)

Returns: V and P (value-result macro parameters)

Definition at line 642 of file vec.h.

◆ vec_add2_ha

#define vec_add2_ha	(	V,
		P,
		N,
		H,
		A
	)

Value:

do {                                                                            \
  word _v(n) = (N);                                                             \
  word _v(l) = vec_len (V);                                                     \
  V = _vec_resize ((V), _v(n), (_v(l) + _v(n)) * sizeof ((V)[0]), (H), (A));    \
  P = (V) + _v(l);                                                              \
} while (0)

Add N elements to end of vector V, return pointer to new elements in P.

(general version)

Parameters

V	pointer to a vector
P	pointer to new vector element(s)
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V and P (value-result macro parameters)

Definition at line 613 of file vec.h.

◆ vec_add_aligned

#define vec_add_aligned	(	V,
		E,
		N,
		A
	)	vec_add_ha(V,E,N,0,A)

Add N elements to end of vector V (no header, specified alignment)

Parameters

V	pointer to a vector
E	pointer to element(s) to add
N	number of elements to add
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 678 of file vec.h.

◆ vec_add_ha

#define vec_add_ha	(	V,
		E,
		N,
		H,
		A
	)

Value:

do {                                                                            \
  word _v(n) = (N);                                                             \
  word _v(l) = vec_len (V);                                                     \
  V = _vec_resize ((V), _v(n), (_v(l) + _v(n)) * sizeof ((V)[0]), (H), (A));    \
  clib_memcpy_fast ((V) + _v(l), (E), _v(n) * sizeof ((V)[0]));                 \
} while (0)

Add N elements to end of vector V (general version)

Parameters

V	pointer to a vector
E	pointer to element(s) to add
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 653 of file vec.h.

◆ vec_alloc

#define vec_alloc	(	V,
		N
	)	vec_alloc_ha(V,N,0,0)

Allocate space for N more elements (no header, unspecified alignment)

Parameters

V	pointer to a vector
N	number of elements to add

Returns: V (value-result macro parameter)

Definition at line 319 of file vec.h.

◆ vec_alloc_aligned

#define vec_alloc_aligned	(	V,
		N,
		A
	)	vec_alloc_ha(V,N,0,A)

Allocate space for N more elements (no header, given alignment)

Parameters

V	pointer to a vector
N	number of elements to add
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 328 of file vec.h.

◆ vec_alloc_ha

#define vec_alloc_ha	(	V,
		N,
		H,
		A
	)

Value:

do {                                            \
    uword _v(l) = vec_len (V);                  \
    vec_resize_ha (V, N, H, A);                 \
    _vec_len (V) = _v(l);                       \
} while (0)

Allocate space for N more elements.

Parameters

V	pointer to a vector
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 305 of file vec.h.

◆ vec_append

#define vec_append	(	v1,
		v2
	)

Value:

do {                                                                    \
  uword _v(l1) = vec_len (v1);                                          \
  uword _v(l2) = vec_len (v2);                                          \
                                                                        \
  v1 = _vec_resize ((v1), _v(l2),                                       \
                    (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, 0);        \
  clib_memcpy_fast ((v1) + _v(l1), (v2), _v(l2) * sizeof ((v2)[0]));            \
} while (0)

Append v2 after v1.

Result in v1.

Parameters

V1	target vector
V2	vector to append

Definition at line 890 of file vec.h.

◆ vec_append_aligned

#define vec_append_aligned	(	v1,
		v2,
		align
	)

Value:

do {                                                                    \
  uword _v(l1) = vec_len (v1);                                          \
  uword _v(l2) = vec_len (v2);                                          \
                                                                        \
  v1 = _vec_resize ((v1), _v(l2),                                       \
                    (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, align);    \
  clib_memcpy_fast ((v1) + _v(l1), (v2), _v(l2) * sizeof ((v2)[0]));            \
} while (0)

Append v2 after v1.

Result in v1. Specified alignment.

Parameters

V1	target vector
V2	vector to append
align	required alignment

Definition at line 906 of file vec.h.

◆ vec_c_string_is_terminated

#define vec_c_string_is_terminated ( V ) (((V) != 0) && (vec_len (V) != 0) && ((V)[vec_len ((V)) - 1] == 0))

Test whether a vector is a NULL terminated c-string.

Parameters

V	(possibly NULL) pointer to a vector.

Returns: BOOLEAN indicating if the vector c-string is null terminated.

Definition at line 1082 of file vec.h.

◆ vec_clone

#define vec_clone	(	NEW_V,
		OLD_V
	)

Value:

do {                                                                            \
  (NEW_V) = 0;                                                                  \
  (NEW_V) = _vec_resize ((NEW_V), vec_len (OLD_V),                              \
                         vec_len (OLD_V) * sizeof ((NEW_V)[0]), (0), (0));      \
} while (0)

Clone a vector.

Make a new vector with the same size as a given vector but possibly with a different type.

Parameters

NEW_V	pointer to new vector
OLD_V	pointer to old vector

Definition at line 455 of file vec.h.

◆ vec_cmp

#define vec_cmp	(	v1,
		v2
	)

Value:

({                                                      \
  word _v(i), _v(cmp), _v(l);                           \
  _v(l) = clib_min (vec_len (v1), vec_len (v2));        \
  _v(cmp) = 0;                                          \
  for (_v(i) = 0; _v(i) < _v(l); _v(i)++) {             \
    _v(cmp) = (v1)[_v(i)] - (v2)[_v(i)];                \
    if (_v(cmp))                                        \
      break;                                            \
  }                                                     \
  if (_v(cmp) == 0 && _v(l) > 0)                        \
    _v(cmp) = vec_len(v1) - vec_len(v2);                \
  (_v(cmp) < 0 ? -1 : (_v(cmp) > 0 ? +1 : 0));          \
})

Compare two vectors (only applicable to vectors of signed numbers).

Used in qsort compare functions.

Parameters

v1	Pointer to a vector
v2	Pointer to a vector

Returns: -1, 0, +1

Definition at line 991 of file vec.h.

◆ vec_copy

#define vec_copy	(	DST,
		SRC
	)

Value:

clib_memcpy_fast (DST, SRC, vec_len (DST) * \

sizeof ((DST)[0]))

clib_memcpy_fast

#define clib_memcpy_fast(a, b, c)

Definition: string.h:81

vec_len

#define vec_len(v)

Number of elements in vector (rvalue-only, NULL tolerant)

Definition: vec_bootstrap.h:142

Copy a vector, memcpy wrapper.

Assumes sizeof(SRC[0]) == sizeof(DST[0])

Parameters

DST	destination
SRC	source

Definition at line 446 of file vec.h.

◆ vec_del1

#define vec_del1	(	v,
		i
	)

Value:

do {                                            \
  uword _vec_del_l = _vec_len (v) - 1;          \
  uword _vec_del_i = (i);                       \
  if (_vec_del_i < _vec_del_l)                  \
    (v)[_vec_del_i] = (v)[_vec_del_l];          \
  _vec_len (v) = _vec_del_l;                    \
  CLIB_MEM_POISON(vec_end(v), sizeof ((v)[0])); \
} while (0)

Delete the element at index I.

Parameters

V	pointer to a vector
I	index to delete

Definition at line 875 of file vec.h.

◆ vec_delete

#define vec_delete	(	V,
		N,
		M
	)

Value:

do {                                                            \
  word _v(l) = vec_len (V);                                     \
  word _v(n) = (N);                                             \
  word _v(m) = (M);                                             \
  /* Copy over deleted elements. */                             \
  if (_v(l) - _v(n) - _v(m) > 0)                                \
    memmove ((V) + _v(m), (V) + _v(m) + _v(n),                  \
             (_v(l) - _v(n) - _v(m)) * sizeof ((V)[0]));        \
  /* Zero empty space at end (for future re-allocation). */     \
  if (_v(n) > 0)                                                \
    clib_memset ((V) + _v(l) - _v(n), 0, _v(n) * sizeof ((V)[0]));      \
  _vec_len (V) -= _v(n);                                        \
  CLIB_MEM_POISON(vec_end(V), _v(n) * sizeof ((V)[0]));         \
} while (0)

Delete N elements starting at element M.

Parameters

V	pointer to a vector
N	number of elements to delete
M	first element to delete

Returns: V (value-result macro parameter)

Definition at line 854 of file vec.h.

◆ vec_dup

#define vec_dup ( V ) vec_dup_ha(V,0,0)

Return copy of vector (no header, no alignment)

Parameters

V	pointer to a vector

Returns: Vdup copy of vector

Definition at line 429 of file vec.h.

◆ vec_dup_aligned

#define vec_dup_aligned	(	V,
		A
	)	vec_dup_ha(V,0,A)

Return copy of vector (no header, alignment specified).

Parameters

V	pointer to a vector
A	alignment (may be zero)

Returns: Vdup copy of vector

Definition at line 438 of file vec.h.

◆ vec_dup_ha

#define vec_dup_ha	(	V,
		H,
		A
	)	vec_dup_ha_numa(V,H,A,VEC_NUMA_UNSPECIFIED)

Return copy of vector (VEC_NUMA_UNSPECIFIED).

Parameters

V	pointer to a vector
H	size of header in bytes
A	alignment (may be zero)

Returns: Vdup copy of vector

Definition at line 420 of file vec.h.

◆ vec_dup_ha_numa

#define vec_dup_ha_numa	(	V,
		H,
		A,
		S
	)

Value:

({                                                      \
  __typeof__ ((V)[0]) * _v(v) = 0;                      \
  uword _v(l) = vec_len (V);                            \
  if (_v(l) > 0)                                        \
    {                                                   \
      vec_resize_has (_v(v), _v(l), (H), (A), (S));     \
      clib_memcpy_fast (_v(v), (V), _v(l) * sizeof ((V)[0]));\
    }                                                   \
  _v(v);                                                \
})

Return copy of vector (general version).

Parameters

V	pointer to a vector
H	size of header in bytes
A	alignment (may be zero)
S	numa (may be VEC_NUMA_UNSPECIFIED)

Returns: Vdup copy of vector

Definition at line 400 of file vec.h.

◆ vec_free

#define vec_free ( V ) vec_free_h(V,0)

Free vector's memory (no header).

Parameters

V	pointer to a vector

Returns: V (value-result parameter, V=0)

Definition at line 380 of file vec.h.

◆ vec_free_h

#define vec_free_h	(	V,
		H
	)

Value:

do {                                            \
  if (V)                                        \
    {                                           \
      clib_mem_free (vec_header ((V), (H)));    \
      V = 0;                                    \
    }                                           \
} while (0)

Free vector's memory (general version)

Parameters

V	pointer to a vector
H	size of header in bytes

Returns: V (value-result parameter, V=0)

Definition at line 367 of file vec.h.

◆ vec_free_header

#define vec_free_header ( h ) clib_mem_free (h)

Free vector user header (syntactic sugar)

Parameters

h	vector header

Definition at line 388 of file vec.h.

◆ vec_insert

#define vec_insert	(	V,
		N,
		M
	)	vec_insert_ha(V,N,M,0,0)

Insert N vector elements starting at element M, initialize new elements to zero (no header, unspecified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point

Returns: V (value-result macro parameter)

Definition at line 755 of file vec.h.

◆ vec_insert_aligned

#define vec_insert_aligned	(	V,
		N,
		M,
		A
	)	vec_insert_ha(V,N,M,0,A)

Insert N vector elements starting at element M, initialize new elements to zero (no header, alignment specified)

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 766 of file vec.h.

◆ vec_insert_elts

#define vec_insert_elts	(	V,
		E,
		N,
		M
	)	vec_insert_elts_ha(V,E,N,M,0,0)

Insert N vector elements starting at element M, insert given elements (no header, unspecified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
E	element(s) to insert
N	number of elements to insert
M	insertion point

Returns: V (value-result macro parameter)

Definition at line 833 of file vec.h.

◆ vec_insert_elts_aligned

#define vec_insert_elts_aligned	(	V,
		E,
		N,
		M,
		A
	)	vec_insert_elts_ha(V,E,N,M,0,A)

Insert N vector elements starting at element M, insert given elements (no header, specified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
E	element(s) to insert
N	number of elements to insert
M	insertion point
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 845 of file vec.h.

◆ vec_insert_elts_ha

#define vec_insert_elts_ha	(	V,
		E,
		N,
		M,
		H,
		A
	)

Value:

do {                                                    \
  word _v(l) = vec_len (V);                             \
  word _v(n) = (N);                                     \
  word _v(m) = (M);                                     \
  V = _vec_resize ((V),                                 \
                   _v(n),                               \
                   (_v(l) + _v(n))*sizeof((V)[0]),      \
                   (H), (A));                           \
  ASSERT (_v(m) <= _v(l));                              \
  memmove ((V) + _v(m) + _v(n),                         \
           (V) + _v(m),                                 \
           (_v(l) - _v(m)) * sizeof ((V)[0]));          \
  clib_memcpy_fast ((V) + _v(m), (E),                   \
               _v(n) * sizeof ((V)[0]));                \
} while (0)

Insert N vector elements starting at element M, insert given elements (general version)

Parameters

V	(possibly NULL) pointer to a vector.
E	element(s) to insert
N	number of elements to insert
M	insertion point
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 807 of file vec.h.

◆ vec_insert_ha

#define vec_insert_ha	(	V,
		N,
		M,
		H,
		A
	)	vec_insert_init_empty_ha(V,N,M,0,H,A)

Insert N vector elements starting at element M, initialize new elements to zero (general version)

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 745 of file vec.h.

◆ vec_insert_init_empty

#define vec_insert_init_empty	(	V,
		N,
		M,
		INIT
	)	vec_insert_init_empty_ha(V,N,M,INIT,0,0)

Insert N vector elements starting at element M, initialize new elements (no header, unspecified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point
INIT	initial value (can be a complex expression!)

Returns: V (value-result macro parameter)

Definition at line 778 of file vec.h.

◆ vec_insert_init_empty_aligned

#define vec_insert_init_empty_aligned	(	V,
		N,
		M,
		INIT,
		A
	)	vec_insert_init_empty_ha(V,N,M,INIT,0,A)

Insert N vector elements starting at element M, initialize new elements (no header, specified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point
INIT	initial value (can be a complex expression!)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 792 of file vec.h.

◆ vec_insert_init_empty_ha

#define vec_insert_init_empty_ha	(	V,
		N,
		M,
		INIT,
		H,
		A
	)

Value:

do {                                                    \
  word _v(l) = vec_len (V);                             \
  word _v(n) = (N);                                     \
  word _v(m) = (M);                                     \
  V = _vec_resize ((V),                                 \
                   _v(n),                               \
                   (_v(l) + _v(n))*sizeof((V)[0]),      \
                   (H), (A));                           \
  ASSERT (_v(m) <= _v(l));                              \
  memmove ((V) + _v(m) + _v(n),                         \
           (V) + _v(m),                                 \
           (_v(l) - _v(m)) * sizeof ((V)[0]));          \
  clib_memset  ((V) + _v(m), INIT, _v(n) * sizeof ((V)[0]));    \
} while (0)

Insert N vector elements starting at element M, initialize new elements (general version).

Parameters

V	(possibly NULL) pointer to a vector.
N	number of elements to insert
M	insertion point
INIT	initial value (can be a complex expression!)
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 719 of file vec.h.

◆ vec_is_equal

#define vec_is_equal	(	v1,
		v2
	)	(vec_len (v1) == vec_len (v2) && ! memcmp ((v1), (v2), vec_len (v1) * sizeof ((v1)[0])))

Compare two vectors, not NULL-pointer tolerant.

Parameters

v1	Pointer to a vector
v2	Pointer to a vector

Returns: 1 if equal, 0 if unequal

Definition at line 981 of file vec.h.

◆ vec_new

#define vec_new	(	T,
		N
	)	vec_new_ha(T,N,0,0)

Create new vector of given type and length (unspecified alignment, no header).

Parameters

T	type of elements in new vector
N	number of elements to add

Returns: V new vector

Definition at line 350 of file vec.h.

◆ vec_new_aligned

#define vec_new_aligned	(	T,
		N,
		A
	)	vec_new_ha(T,N,0,A)

Create new vector of given type and length (alignment specified, no header).

Parameters

T	type of elements in new vector
N	number of elements to add
A	alignment (may be zero)

Returns: V new vector

Definition at line 359 of file vec.h.

◆ vec_new_ha

#define vec_new_ha	(	T,
		N,
		H,
		A
	)

Value:

({                                                                      \
  word _v(n) = (N);                                                     \
  (T *)_vec_resize ((T *) 0, _v(n), _v(n) * sizeof (T), (H), (A));      \
})

Create new vector of given type and length (general version).

Parameters

T	type of elements in new vector
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V new vector

Definition at line 337 of file vec.h.

◆ vec_pop

#define vec_pop ( V )

Value:

({                                              \
  uword _v(l) = vec_len (V);                    \
  ASSERT (_v(l) > 0);                           \
  _v(l) -= 1;                                   \
  _vec_len (V) = _v (l);                        \
  (V)[_v(l)];                                   \
})

Returns last element of a vector and decrements its length.

Parameters

V	pointer to a vector

Returns: E element removed from the end of the vector

Definition at line 685 of file vec.h.

◆ vec_pop2

#define vec_pop2	(	V,
		E
	)

Value:

({                                              \
  uword _v(l) = vec_len (V);                    \
  if (_v(l) > 0) (E) = vec_pop (V);             \
  _v(l) > 0;                                    \
})

Set E to the last element of a vector, decrement vector length.

Parameters

V	pointer to a vector
E	pointer to the last vector element

Returns: E element removed from the end of the vector (value-result macro parameter

Definition at line 701 of file vec.h.

◆ vec_prepend

#define vec_prepend	(	v1,
		v2
	)

Value:

do {                                                                    \
  uword _v(l1) = vec_len (v1);                                          \
  uword _v(l2) = vec_len (v2);                                          \
                                                                        \
  v1 = _vec_resize ((v1), _v(l2),                                       \
                    (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, 0);        \
  memmove ((v1) + _v(l2), (v1), _v(l1) * sizeof ((v1)[0]));             \
  clib_memcpy_fast ((v1), (v2), _v(l2) * sizeof ((v2)[0]));                  \
} while (0)

Prepend v2 before v1.

Result in v1.

Parameters

V1	target vector
V2	vector to prepend

Definition at line 921 of file vec.h.

◆ vec_prepend_aligned

#define vec_prepend_aligned	(	v1,
		v2,
		align
	)

Value:

do {                                                                    \
  uword _v(l1) = vec_len (v1);                                          \
  uword _v(l2) = vec_len (v2);                                          \
                                                                        \
  v1 = _vec_resize ((v1), _v(l2),                                       \
                    (_v(l1) + _v(l2)) * sizeof ((v1)[0]), 0, align);    \
  memmove ((v1) + _v(l2), (v1), _v(l1) * sizeof ((v1)[0]));             \
  clib_memcpy_fast ((v1), (v2), _v(l2) * sizeof ((v2)[0]));                  \
} while (0)

Prepend v2 before v1.

Result in v1. Specified alignment

Parameters

V1	target vector
V2	vector to prepend
align	required alignment

Definition at line 938 of file vec.h.

◆ vec_resize

#define vec_resize	(	V,
		N
	)	vec_resize_ha(V,N,0,0)

Resize a vector (no header, unspecified alignment) Add N elements to end of given vector V, return pointer to start of vector.

Vector will have room for H header bytes and will have user's data aligned at alignment A (rounded to next power of 2).

Parameters

V	pointer to a vector
N	number of elements to add

Returns: V (value-result macro parameter)

Definition at line 281 of file vec.h.

◆ vec_resize_aligned

#define vec_resize_aligned	(	V,
		N,
		A
	)	vec_resize_ha(V,N,0,A)

Resize a vector (no header, alignment specified).

Add N elements to end of given vector V, return pointer to start of vector. Vector will have room for H header bytes and will have user's data aligned at alignment A (rounded to next power of 2).

Parameters

V	pointer to a vector
N	number of elements to add
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 294 of file vec.h.

◆ vec_resize_ha

#define vec_resize_ha	(	V,
		N,
		H,
		A
	)	vec_resize_has(V,N,H,A,VEC_NUMA_UNSPECIFIED)

Resize a vector (less general version).

Add N elements to end of given vector V, return pointer to start of vector. Vector will have room for H header bytes and will have user's data aligned at alignment A (rounded to next power of 2).

Parameters

V	pointer to a vector
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 270 of file vec.h.

◆ vec_resize_has

#define vec_resize_has	(	V,
		N,
		H,
		A,
		S
	)

Value:

do {                                                            \
  word _v(n) = (N);                                             \
  word _v(l) = vec_len (V);                                     \
  V = _vec_resize_numa ((V), _v(n),                           \
                          (_v(l) + _v(n)) * sizeof ((V)[0]),    \
                          (H), (A),(S));                        \
} while (0)

Resize a vector (general version).

Add N elements to end of given vector V, return pointer to start of vector. Vector will have room for H header bytes and will have user's data aligned at alignment A (rounded to next power of 2).

Parameters

V	pointer to a vector
N	number of elements to add
H	header size in bytes (may be zero)
A	alignment (may be zero)
S	numa_id (may be zero)

Returns: V (value-result macro parameter)

Definition at line 250 of file vec.h.

◆ vec_search

#define vec_search	(	v,
		E
	)

Value:

({                                                      \
  word _v(i) = 0;                                       \
  while (_v(i) < vec_len(v))                            \
  {                                                     \
    if ((v)[_v(i)] == E)                                        \
      break;                                            \
    _v(i)++;                                            \
  }                                                     \
  if (_v(i) == vec_len(v))                              \
    _v(i) = ~0;                                         \
  _v(i);                                                \
})

Search a vector for the index of the entry that matches.

Parameters

v	Pointer to a vector
E	Entry to match

Returns: index of match or ~0

Definition at line 1012 of file vec.h.

◆ vec_search_with_function

#define vec_search_with_function	(	v,
		E,
		fn
	)

Value:

({                                                      \
  word _v(i) = 0;                                       \
  while (_v(i) < vec_len(v))                            \
  {                                                     \
    if (0 != fn(&(v)[_v(i)], (E)))                      \
      break;                                            \
    _v(i)++;                                            \
  }                                                     \
  if (_v(i) == vec_len(v))                              \
    _v(i) = ~0;                                         \
  _v(i);                                                \
})

Search a vector for the index of the entry that matches.

Parameters

v	Pointer to a vector
E	Pointer to entry to match
fn	Comparison function !0 => match

Returns: index of match or ~0

Definition at line 1033 of file vec.h.

◆ vec_set

#define vec_set	(	v,
		val
	)

Value:

do {                                            \
  word _v(i);                                   \
  __typeof__ ((v)[0]) _val = (val);             \
  for (_v(i) = 0; _v(i) < vec_len (v); _v(i)++) \
    (v)[_v(i)] = _val;                          \
} while (0)

Set all vector elements to given value.

Null-pointer tolerant.

Parameters

v	vector to set
val	value for each vector element

Definition at line 963 of file vec.h.

◆ vec_sort_with_function

#define vec_sort_with_function	(	vec,
		f
	)

Value:

do {                                                            \
  if (vec_len (vec) > 1)                                        \
    qsort (vec, vec_len (vec), sizeof (vec[0]), (void *) (f));  \
} while (0)

Sort a vector using the supplied element comparison function.

Does not depend on the underlying implementation to deal correctly with null, zero-long, or 1-long vectors

Parameters

vec	vector to sort
f	comparison function

Definition at line 1055 of file vec.h.

◆ vec_terminate_c_string

#define vec_terminate_c_string ( V )

Value:

do {                                          \
    u32 vl = vec_len ((V));                     \
    if (!vec_c_string_is_terminated(V))         \
      {                                         \
        vec_validate ((V), vl);                 \
        (V)[vl] = 0;                            \
      }                                         \
  } while (0)

(If necessary) NULL terminate a vector containing a c-string.

Parameters

V	(possibly NULL) pointer to a vector.

Returns: V (value-result macro parameter)

Definition at line 1090 of file vec.h.

◆ vec_validate

#define vec_validate	(	V,
		I
	)	vec_validate_ha(V,I,0,0)

Make sure vector is long enough for given index (no header, unspecified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return

Returns: V (value-result macro parameter)

Definition at line 509 of file vec.h.

◆ vec_validate_aligned

#define vec_validate_aligned	(	V,
		I,
		A
	)	vec_validate_ha(V,I,0,A)

Make sure vector is long enough for given index (no header, specified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 520 of file vec.h.

◆ vec_validate_ha

#define vec_validate_ha	(	V,
		I,
		H,
		A
	)	vec_validate_han(V,I,H,A,VEC_NUMA_UNSPECIFIED)

Definition at line 500 of file vec.h.

◆ vec_validate_han

#define vec_validate_han	(	V,
		I,
		H,
		A,
		N
	)

Value:

do {                                                                    \
  void *oldheap;                                                        \
  STATIC_ASSERT(A==0 || ((A % sizeof(V[0]))==0)                         \
        || ((sizeof(V[0]) % A) == 0),                                   \
    "vector validate aligned on incorrectly sized object");             \
  word _v(i) = (I);                                                     \
  word _v(l) = vec_len (V);                                             \
  if (_v(i) >= _v(l))                                                   \
    {                                                                   \
      /* switch to the per-numa heap if directed */                   \
      if (PREDICT_FALSE(N != VEC_NUMA_UNSPECIFIED))                   \
        {                                                               \
           oldheap = clib_mem_get_per_cpu_heap();                       \
           clib_mem_set_per_cpu_heap (clib_mem_get_per_numa_heap(N)); \
        }                                                               \
                                                                        \
      vec_resize_ha ((V), 1 + (_v(i) - _v(l)), (H), (A));               \
      /* Must zero new space since user may have previously             \
         used e.g. _vec_len (v) -= 10 */                                \
      clib_memset ((V) + _v(l), 0,                                      \
                   (1 + (_v(i) - _v(l))) * sizeof ((V)[0]));            \
      /* Switch back to the global heap */                              \
      if (PREDICT_FALSE (N != VEC_NUMA_UNSPECIFIED))                  \
        clib_mem_set_per_cpu_heap (oldheap);                            \
    }                                                                   \
} while (0)

Make sure vector is long enough for given index (general version).

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return
H	header size in bytes (may be zero)
A	alignment (may be zero)
N	numa_id (may be zero)

Returns: V (value-result macro parameter)

Definition at line 472 of file vec.h.

◆ vec_validate_init_c_string

#define vec_validate_init_c_string	(	V,
		S,
		L
	)

Value:

do {                                          \
    vec_reset_length (V);                       \
    vec_validate ((V), (L));                    \
    if ((S) && (L))                             \
        clib_memcpy_fast ((V), (S), (L));            \
    (V)[(L)] = 0;                               \
  } while (0)

Make a vector containing a NULL terminated c-string.

Parameters

V	(possibly NULL) pointer to a vector.
S	pointer to string buffer.
L	string length (NOT including the terminating NULL; a la strlen())

Definition at line 1067 of file vec.h.

◆ vec_validate_init_empty

#define vec_validate_init_empty	(	V,
		I,
		INIT
	)	vec_validate_init_empty_ha(V,I,INIT,0,0)

Make sure vector is long enough for given index and initialize empty space (no header, unspecified alignment)

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return
INIT	initial value (can be a complex expression!)

Returns: V (value-result macro parameter)

Definition at line 556 of file vec.h.

◆ vec_validate_init_empty_aligned

#define vec_validate_init_empty_aligned	(	V,
		I,
		INIT,
		A
	)	vec_validate_init_empty_ha(V,I,INIT,0,A)

Make sure vector is long enough for given index and initialize empty space (no header, alignment alignment)

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return
INIT	initial value (can be a complex expression!)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 568 of file vec.h.

◆ vec_validate_init_empty_ha

#define vec_validate_init_empty_ha	(	V,
		I,
		INIT,
		H,
		A
	)

Value:

do {                                                            \
  word _v(i) = (I);                                             \
  word _v(l) = vec_len (V);                                     \
  if (_v(i) >= _v(l))                                           \
    {                                                           \
      vec_resize_ha ((V), 1 + (_v(i) - _v(l)), (H), (A));       \
      while (_v(l) <= _v(i))                                    \
        {                                                       \
          (V)[_v(l)] = (INIT);                                  \
          _v(l)++;                                              \
        }                                                       \
    }                                                           \
} while (0)

Make sure vector is long enough for given index and initialize empty space (general version)

Parameters

V	(possibly NULL) pointer to a vector.
I	vector index which will be valid upon return
INIT	initial value (can be a complex expression!)
H	header size in bytes (may be zero)
A	alignment (may be zero)

Returns: V (value-result macro parameter)

Definition at line 532 of file vec.h.

◆ vec_zero

#define vec_zero ( var )

Value:

do {                                                            \
  if (var)                                                      \
    clib_memset ((var), 0, vec_len (var) * sizeof ((var)[0]));  \
} while (0)

Zero all vector elements.

Null-pointer tolerant.

Parameters

var	Vector to zero

Definition at line 953 of file vec.h.

Function Documentation

◆ clib_mem_is_vec()

static uword clib_mem_is_vec ( void * v )

inlinestatic

Predicate function, says whether the supplied vector is a clib heap object.

Parameters

v	pointer to a vector

Returns: 0 or 1

Definition at line 229 of file vec.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clib_mem_is_vec_h()

uword clib_mem_is_vec_h	(	void *	v,
		uword	header_bytes
	)

Predicate function, says whether the supplied vector is a clib heap object (general version).

Parameters

v	pointer to a vector
header_bytes	vector header size in bytes (may be zero)

Returns: 0 or 1

Definition at line 138 of file vec.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ vec_free_not_inline()

void vec_free_not_inline ( void * v )

Definition at line 150 of file vec.c.

Here is the call graph for this function:

◆ vec_resize_allocate_memory()

void* vec_resize_allocate_memory	(	void *	v,
		word	length_increment,
		uword	data_bytes,
		uword	header_bytes,
		uword	data_align,
		uword	numa_id
	)

Low-level resize allocation function, usually not called directly.

Parameters

v	pointer to a vector
length_increment	length increment in elements
data_bytes	requested size in bytes
header_bytes	header size in bytes (may be zero)
data_align	alignment (may be zero)
numa_id	numa id (may be zero)

Returns: v_prime pointer to resized vector, may or may not equal v

Definition at line 44 of file vec.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ vec_add

◆ vec_add1

◆ vec_add1_aligned

◆ vec_add1_ha

◆ vec_add2

◆ vec_add2_aligned

◆ vec_add2_ha

◆ vec_add_aligned

◆ vec_add_ha

◆ vec_alloc

◆ vec_alloc_aligned

◆ vec_alloc_ha

◆ vec_append

◆ vec_append_aligned

◆ vec_c_string_is_terminated

◆ vec_clone

◆ vec_cmp

◆ vec_copy

◆ vec_del1

◆ vec_delete

◆ vec_dup

◆ vec_dup_aligned

◆ vec_dup_ha

◆ vec_dup_ha_numa

◆ vec_free

◆ vec_free_h

◆ vec_free_header

◆ vec_insert

◆ vec_insert_aligned

◆ vec_insert_elts

◆ vec_insert_elts_aligned

◆ vec_insert_elts_ha

◆ vec_insert_ha

◆ vec_insert_init_empty

◆ vec_insert_init_empty_aligned

◆ vec_insert_init_empty_ha

◆ vec_is_equal

◆ vec_new

◆ vec_new_aligned

◆ vec_new_ha

◆ vec_pop

◆ vec_pop2

◆ vec_prepend

◆ vec_prepend_aligned

◆ vec_resize

◆ vec_resize_aligned

◆ vec_resize_ha

◆ vec_resize_has

◆ vec_search

◆ vec_search_with_function

◆ vec_set

◆ vec_sort_with_function

◆ vec_terminate_c_string

◆ vec_validate

◆ vec_validate_aligned

◆ vec_validate_ha

◆ vec_validate_han

◆ vec_validate_init_c_string

◆ vec_validate_init_empty

◆ vec_validate_init_empty_aligned

◆ vec_validate_init_empty_ha

◆ vec_zero

Function Documentation

◆ clib_mem_is_vec()

◆ clib_mem_is_vec_h()

◆ vec_free_not_inline()

◆ vec_resize_allocate_memory()