/** \file
    Vector bootstrap header file
*/

/* Bootstrap include so that #include <vppinfra/mem.h> can include e.g.
   <vppinfra/mheap.h> which depends on <vppinfra/vec.h>. */

/** \brief vector header structure

   Bookkeeping header preceding vector elements in memory.
   User header information may preceed standard vec header.
   If you change u32 len -> u64 len, single vectors can
   exceed 2**32 elements. Clib heaps are vectors. */

typedef struct
{
#if CLIB_VEC64 > 0
  u64 len;
#else
  u32 len; /**< Number of elements in vector (NOT its allocated length). */
  u32 dlmalloc_header_offset;	/**< offset to memory allocator offset  */
#endif
  u8 vector_data[0];  /**< Vector data . */
} vec_header_t;
 

向量即動態陣列，這裡的vec_header_t只是動態陣列的頭結構，表示這個陣列有多少個數組元素，即它的規模。陣列0號元素的位置是vector_data對應的記憶體地址。

使用這個結構的時候，也可以在vec_header_t前再加1個額外的頭結構，描述這個具體動態陣列整體更詳細的一些資訊，這個具體使用時具體分析。

dlmalloc_header_offset暫不分析。

/** \brief Find the vector header

    Given the user's pointer to a vector, find the corresponding
    vector header

    @param v pointer to a vector
    @return pointer to the vector's vector_header_t
*/
#define _vec_find(v)	((vec_header_t *) (v) - 1)
 

根據動態陣列0號元素的地址計算出vec_header_t頭部的地址

#define _vec_round_size(s) \
  (((s) + sizeof (uword) - 1) &~ (sizeof (uword) - 1))

可能增加s的值，使得其是cpu字長的整數倍。如4的整數倍或者8的整數倍

always_inline uword
vec_header_bytes (uword header_bytes)
{
  return round_pow2 (header_bytes + sizeof (vec_header_t),
		     sizeof (vec_header_t));
}
 

使用者定義的頭部長度加上動態陣列自己的頭部長度，並8位元組對齊。

使用者定義的頭部長度可以為0。

/** \brief Find a user vector header

    Finds the user header of a vector with unspecified alignment given
    the user pointer to the vector.
*/

always_inline void *
vec_header (void *v, uword header_bytes)
{
  return v - vec_header_bytes (header_bytes);
}

根據動態陣列第0號元素的地址獲取使用者自定義頭的記憶體地址，如果沒有使用者自定義頭，則獲取到的是動態陣列頭的地址。

/** \brief Find the end of user vector header

    Finds the end of the user header of a vector with unspecified
    alignment given the user pointer to the vector.
*/

always_inline void *
vec_header_end (void *v, uword header_bytes)
{
  return v + vec_header_bytes (header_bytes);
}

根據使用者自定義頭的記憶體地址，獲取動態陣列第0號元素的地址

always_inline uword
vec_aligned_header_bytes (uword header_bytes, uword align)
{
  return round_pow2 (header_bytes + sizeof (vec_header_t), align);
}

always_inline void *
vec_aligned_header (void *v, uword header_bytes, uword align)
{
  return v - vec_aligned_header_bytes (header_bytes, align);
}

always_inline void *
vec_aligned_header_end (void *v, uword header_bytes, uword align)
{
  return v + vec_aligned_header_bytes (header_bytes, align);
}

和前面的程式碼類似，只是不再是8位元組記憶體對齊，而是通過align引數來控制對齊。

/** \brief Number of elements in vector (lvalue-capable)

   _vec_len (v) does not check for null, but can be used as a lvalue
   (e.g. _vec_len (v) = 99).
*/

#define _vec_len(v)	(_vec_find(v)->len)

讀取動態陣列的元素個數，可以作為左值，進行賦值

/** \brief Number of elements in vector (rvalue-only, NULL tolerant)

    vec_len (v) checks for NULL, but cannot be used as an lvalue.
    If in doubt, use vec_len...
*/

#define vec_len(v)	((v) ? _vec_len(v) : 0)

同上，只能做為右值，但右空指標判斷。

如果v為空指標，表示當前動態陣列沒有有效的元素，可能只有陣列頭部，也可能有使用者自定義的頭部，還可能動態陣列的記憶體空間已經申請好，只是沒有使用而已。

/** \brief Reset vector length to zero
    NULL-pointer tolerant
*/

#define vec_reset_length(v) do { if (v) _vec_len (v) = 0; } while (0)

將陣列長度置0，其實就是宣佈當前陣列中的內容失效。

/** \brief Number of data bytes in vector. */

#define vec_bytes(v) (vec_len (v) * sizeof (v[0]))

計算當前陣列資料部分已佔用的記憶體空間(位元組數). 即每一個數組元素的大小乘以陣列元素個數

/** \brief Total number of bytes that can fit in vector with current allocation. */

#define vec_capacity(v,b)							\
({										\
  void * _vec_capacity_v = (void *) (v);					\
  uword _vec_capacity_b = (b);							\
  _vec_capacity_b = sizeof (vec_header_t) + _vec_round_size (_vec_capacity_b);	\
  _vec_capacity_v ? clib_mem_size (_vec_capacity_v - _vec_capacity_b) : 0;	\
})

計算動態陣列佔用的記憶體空間，也包含2種類型的頭部，不僅僅是資料部分

/** \brief Total number of elements that can fit into vector. */
#define vec_max_len(v) (vec_capacity(v,0) / sizeof (v[0]))

當前已分配的記憶體最多容納的元素個數，實際上達不到，因為忽略了8位元組的陣列頭部。

/** \brief End (last data address) of vector. */
#define vec_end(v)	((v) + vec_len (v))

當前陣列元素的最後一個元素的下一個位置，新元素在這裡追加

/** \brief True if given pointer is within given vector. */
#define vec_is_member(v,e) ((e) >= (v) && (e) < vec_end (v))

判斷一個元素是否合法的陣列元素，是否越界

/** \brief Get vector value at index i checking that i is in bounds. */
#define vec_elt_at_index(v,i)			\
({						\
  ASSERT ((i) < vec_len (v));			\
  (v) + (i);					\
})

讀取第i號陣列元素

/** \brief Get vector value at index i */
#define vec_elt(v,i) (vec_elt_at_index(v,i))[0]

同上，不過不是指標形式，而是結構體形式。

/** \brief Vector iterator */
#define vec_foreach(var,vec) for (var = (vec); var < vec_end (vec); var++)

/** \brief Vector iterator (reverse) */
#define vec_foreach_backwards(var,vec) \
for (var = vec_end (vec) - 1; var >= (vec); var--)

/** \brief Iterate over vector indices. */
#define vec_foreach_index(var,v) for ((var) = 0; (var) < vec_len (v); (var)++)

/** \brief Iterate over vector indices (reverse). */
#define vec_foreach_index_backwards(var,v) \
  for ((var) = vec_len((v)) - 1; (var) >= 0; (var)--)

以指標或者下標形式遍歷動態陣列中的每一個元素