FD.io VPP  v20.05.1-5-g09f167997
Vector Packet Processing
vec.h File Reference

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

+ Include dependency graph for vec.h:

Go to the source code of this file.

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

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
Vpointer to a vector
Epointer to element(s) to add
Nnumber of elements to add
Returns
V (value-result macro parameter)

Definition at line 666 of file vec.h.

◆ vec_add1

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

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

Parameters
Vpointer to a vector
Eelement to add
Returns
V (value-result macro parameter)

Definition at line 590 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
Vpointer to a vector
Eelement to add
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 599 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)
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
Vpointer to a vector
Eelement to add
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 577 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
Vpointer to a vector
Ppointer to new vector element(s)
Nnumber of elements to add
Returns
V and P (value-result macro parameters)

Definition at line 628 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
Vpointer to a vector
Ppointer to new vector element(s)
Nnumber of elements to add
Aalignment (may be zero)
Returns
V and P (value-result macro parameters)

Definition at line 640 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)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

(general version)

Parameters
Vpointer to a vector
Ppointer to new vector element(s)
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V and P (value-result macro parameters)

Definition at line 611 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
Vpointer to a vector
Epointer to element(s) to add
Nnumber of elements to add
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 676 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)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
Vpointer to a vector
Epointer to element(s) to add
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 651 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
Vpointer to a vector
Nnumber 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
Vpointer to a vector
Nnumber of elements to add
Aalignment (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)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Allocate space for N more elements.

Parameters
Vpointer to a vector
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Append v2 after v1.

Result in v1.

Parameters
V1target vector
V2vector to append

Definition at line 888 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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Append v2 after v1.

Result in v1. Specified alignment.

Parameters
V1target vector
V2vector to append
alignrequired alignment

Definition at line 904 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 1080 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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Clone a vector.

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

Parameters
NEW_Vpointer to new vector
OLD_Vpointer to old vector

Definition at line 453 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)); \
})
#define clib_min(x, y)
Definition: clib.h:319
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Used in qsort compare functions.

Parameters
v1Pointer to a vector
v2Pointer to a vector
Returns
-1, 0, +1

Definition at line 989 of file vec.h.

◆ vec_copy

#define vec_copy (   DST,
  SRC 
)
Value:
clib_memcpy_fast (DST, SRC, vec_len (DST) * \
sizeof ((DST)[0]))
#define clib_memcpy_fast(a, b, c)
Definition: string.h:81
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Copy a vector, memcpy wrapper.

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

Parameters
DSTdestination
SRCsource

Definition at line 444 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)
#define vec_end(v)
End (last data address) of vector.
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317

Delete the element at index I.

Parameters
Vpointer to a vector
Iindex to delete

Definition at line 873 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)
#define vec_end(v)
End (last data address) of vector.
#define N
Definition: aes_cbc.c:225
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
#define M(T, mp)

Delete N elements starting at element M.

Parameters
Vpointer to a vector
Nnumber of elements to delete
Mfirst element to delete
Returns
V (value-result macro parameter)

Definition at line 852 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
Vpointer to a vector
Returns
Vdup copy of vector

Definition at line 427 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
Vpointer to a vector
Aalignment (may be zero)
Returns
Vdup copy of vector

Definition at line 436 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
Vpointer to a vector
Hsize of header in bytes
Aalignment (may be zero)
Returns
Vdup copy of vector

Definition at line 418 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); \
})
#define S(mp)
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Return copy of vector (general version).

Parameters
Vpointer to a vector
Hsize of header in bytes
Aalignment (may be zero)
Snuma (may be VEC_NUMA_UNSPECIFIED)
Returns
Vdup copy of vector

Definition at line 398 of file vec.h.

◆ vec_free

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

Free vector's memory (no header).

Parameters
Vpointer 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,
 
)
Value:
do { \
if (V) \
{ \
clib_mem_free (vec_header ((V), (H))); \
V = 0; \
} \
} while (0)
static void * vec_header(void *v, uword header_bytes)
Find a user vector header.
Definition: vec_bootstrap.h:92

Free vector's memory (general version)

Parameters
Vpointer to a vector
Hsize 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
hvector header

Definition at line 386 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.
Nnumber of elements to insert
Minsertion point
Returns
V (value-result macro parameter)

Definition at line 753 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.
Nnumber of elements to insert
Minsertion point
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 764 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.
Eelement(s) to insert
Nnumber of elements to insert
Minsertion point
Returns
V (value-result macro parameter)

Definition at line 831 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.
Eelement(s) to insert
Nnumber of elements to insert
Minsertion point
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 843 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)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
#define M(T, mp)

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

Parameters
V(possibly NULL) pointer to a vector.
Eelement(s) to insert
Nnumber of elements to insert
Minsertion point
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 805 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.
Nnumber of elements to insert
Minsertion point
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 743 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.
Nnumber of elements to insert
Minsertion point
INITinitial value (can be a complex expression!)
Returns
V (value-result macro parameter)

Definition at line 776 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.
Nnumber of elements to insert
Minsertion point
INITinitial value (can be a complex expression!)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 790 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)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)
#define M(T, mp)

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

Parameters
V(possibly NULL) pointer to a vector.
Nnumber of elements to insert
Minsertion point
INITinitial value (can be a complex expression!)
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 717 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
v1Pointer to a vector
v2Pointer to a vector
Returns
1 if equal, 0 if unequal

Definition at line 979 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
Ttype of elements in new vector
Nnumber 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
Ttype of elements in new vector
Nnumber of elements to add
Aalignment (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)); \
})
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048

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

Parameters
Ttype of elements in new vector
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (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)]; \
})
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Returns last element of a vector and decrements its length.

Parameters
Vpointer to a vector
Returns
E element removed from the end of the vector

Definition at line 683 of file vec.h.

◆ vec_pop2

#define vec_pop2 (   V,
 
)
Value:
({ \
uword _v(l) = vec_len (V); \
if (_v(l) > 0) (E) = vec_pop (V); \
_v(l) > 0; \
})
#define vec_pop(V)
Returns last element of a vector and decrements its length.
Definition: vec.h:683
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
Vpointer to a vector
Epointer to the last vector element
Returns
E element removed from the end of the vector (value-result macro parameter

Definition at line 699 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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Prepend v2 before v1.

Result in v1.

Parameters
V1target vector
V2vector to prepend

Definition at line 919 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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Prepend v2 before v1.

Result in v1. Specified alignment

Parameters
V1target vector
V2vector to prepend
alignrequired alignment

Definition at line 936 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
Vpointer to a vector
Nnumber 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
Vpointer to a vector
Nnumber of elements to add
Aalignment (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
Vpointer to a vector
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (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)
#define S(mp)
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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
Vpointer to a vector
Nnumber of elements to add
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Snuma_id (may be zero)
Returns
V (value-result macro parameter)

Definition at line 250 of file vec.h.

◆ vec_search

#define vec_search (   v,
 
)
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); \
})
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
vPointer to a vector
EEntry to match
Returns
index of match or ~0

Definition at line 1010 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); \
})
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
vPointer to a vector
EPointer to entry to match
fnComparison function !0 => match
Returns
index of match or ~0

Definition at line 1031 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)
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Set all vector elements to given value.

Null-pointer tolerant.

Parameters
vvector to set
valvalue for each vector element

Definition at line 961 of file vec.h.

◆ vec_sort_with_function

#define vec_sort_with_function (   vec,
 
)
Value:
do { \
if (vec_len (vec) > 1) \
qsort (vec, vec_len (vec), sizeof (vec[0]), (void *) (f)); \
} while (0)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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
vecvector to sort
fcomparison function

Definition at line 1053 of file vec.h.

◆ vec_terminate_c_string

#define vec_terminate_c_string (   V)
Value:
do { \
u32 vl = vec_len ((V)); \
{ \
vec_validate ((V), vl); \
(V)[vl] = 0; \
} \
} while (0)
#define vec_c_string_is_terminated(V)
Test whether a vector is a NULL terminated c-string.
Definition: vec.h:1080
u32 vl(void *p)
GDB callable function: vl - Return vector length of vector.
Definition: gdb_funcs.c:35
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

(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 1088 of file vec.h.

◆ vec_validate

#define vec_validate (   V,
 
)    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.
Ivector index which will be valid upon return
Returns
V (value-result macro parameter)

Definition at line 507 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.
Ivector index which will be valid upon return
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 518 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 498 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 */ \
{ \
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 */ \
clib_mem_set_per_cpu_heap (oldheap); \
} \
} while (0)
#define VEC_NUMA_UNSPECIFIED
Definition: mem.h:58
static void * clib_mem_get_per_cpu_heap(void)
Definition: mem.h:65
#define PREDICT_FALSE(x)
Definition: clib.h:118
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define vec_resize_ha(V, N, H, A)
Resize a vector (less general version).
Definition: vec.h:270
static void * clib_mem_get_per_numa_heap(u32 numa_id)
Definition: mem.h:81
#define N
Definition: aes_cbc.c:225
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
V(possibly NULL) pointer to a vector.
Ivector index which will be valid upon return
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Nnuma_id (may be zero)
Returns
V (value-result macro parameter)

Definition at line 470 of file vec.h.

◆ vec_validate_init_c_string

#define vec_validate_init_c_string (   V,
  S,
 
)
Value:
do { \
vec_reset_length (V); \
vec_validate ((V), (L)); \
if ((S) && (L)) \
clib_memcpy_fast ((V), (S), (L)); \
(V)[(L)] = 0; \
} while (0)
#define S(mp)

Make a vector containing a NULL terminated c-string.

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

Definition at line 1065 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.
Ivector index which will be valid upon return
INITinitial value (can be a complex expression!)
Returns
V (value-result macro parameter)

Definition at line 554 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.
Ivector index which will be valid upon return
INITinitial value (can be a complex expression!)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 566 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)
sll srl srl sll sra u16x4 i
Definition: vector_sse42.h:317
#define A(x)
Definition: main.c:1048
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

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

Parameters
V(possibly NULL) pointer to a vector.
Ivector index which will be valid upon return
INITinitial value (can be a complex expression!)
Hheader size in bytes (may be zero)
Aalignment (may be zero)
Returns
V (value-result macro parameter)

Definition at line 530 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)
#define vec_len(v)
Number of elements in vector (rvalue-only, NULL tolerant)

Zero all vector elements.

Null-pointer tolerant.

Parameters
varVector to zero

Definition at line 951 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
vpointer 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
vpointer to a vector
header_bytesvector 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_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
vpointer to a vector
length_incrementlength increment in elements
data_bytesrequested size in bytes
header_bytesheader size in bytes (may be zero)
data_alignalignment (may be zero)
numa_idnuma 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.