DPDK  20.08.0
Macros | Functions
rte_stack.h File Reference
#include <rte_atomic.h>
#include <rte_compat.h>
#include <rte_debug.h>
#include <rte_errno.h>
#include <rte_memzone.h>
#include <rte_spinlock.h>
#include "rte_stack_std.h"
#include "rte_stack_lf.h"

Go to the source code of this file.

Macros

#define RTE_STACK_NAMESIZE
 
#define RTE_STACK_F_LF   0x0001
 

Functions

static __rte_experimental __rte_always_inline unsigned int rte_stack_push (struct rte_stack *s, void *const *obj_table, unsigned int n)
 
static __rte_experimental __rte_always_inline unsigned int rte_stack_pop (struct rte_stack *s, void **obj_table, unsigned int n)
 
static __rte_experimental __rte_always_inline unsigned int rte_stack_count (struct rte_stack *s)
 
static __rte_experimental __rte_always_inline unsigned int rte_stack_free_count (struct rte_stack *s)
 
__rte_experimental struct rte_stack * rte_stack_create (const char *name, unsigned int count, int socket_id, uint32_t flags)
 
__rte_experimental void rte_stack_free (struct rte_stack *s)
 
__rte_experimental struct rte_stack * rte_stack_lookup (const char *name)
 

Detailed Description

RTE Stack.

Warning
EXPERIMENTAL: All functions in this file may be changed or removed without prior notice.

librte_stack provides an API for configuration and use of a bounded stack of pointers. Push and pop operations are MT-safe, allowing concurrent access, and the interface supports pushing and popping multiple pointers at a time.

Definition in file rte_stack.h.

Macro Definition Documentation

#define RTE_STACK_NAMESIZE
Value:
sizeof(RTE_STACK_MZ_PREFIX) + 1)
#define RTE_MEMZONE_NAMESIZE
Definition: rte_memzone.h:51

The maximum length of a stack name.

Definition at line 36 of file rte_stack.h.

#define RTE_STACK_F_LF   0x0001

The stack uses lock-free push and pop functions. This flag is only supported on x86_64 platforms, currently.

Definition at line 98 of file rte_stack.h.

Function Documentation

static __rte_experimental __rte_always_inline unsigned int rte_stack_push ( struct rte_stack *  s,
void *const *  obj_table,
unsigned int  n 
)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Push several objects on the stack (MT-safe).

Parameters
sA pointer to the stack structure.
obj_tableA pointer to a table of void * pointers (objects).
nThe number of objects to push on the stack from the obj_table.
Returns
Actual number of objects pushed (either 0 or n).

Definition at line 120 of file rte_stack.h.

static __rte_experimental __rte_always_inline unsigned int rte_stack_pop ( struct rte_stack *  s,
void **  obj_table,
unsigned int  n 
)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Pop several objects from the stack (MT-safe).

Parameters
sA pointer to the stack structure.
obj_tableA pointer to a table of void * pointers (objects).
nThe number of objects to pull from the stack.
Returns
Actual number of objects popped (either 0 or n).

Definition at line 148 of file rte_stack.h.

static __rte_experimental __rte_always_inline unsigned int rte_stack_count ( struct rte_stack *  s)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Return the number of used entries in a stack.

Parameters
sA pointer to the stack structure.
Returns
The number of used entries in the stack.

Definition at line 172 of file rte_stack.h.

static __rte_experimental __rte_always_inline unsigned int rte_stack_free_count ( struct rte_stack *  s)
static
Warning
EXPERIMENTAL: this API may change without prior notice

Return the number of free entries in a stack.

Parameters
sA pointer to the stack structure.
Returns
The number of free entries in the stack.

Definition at line 195 of file rte_stack.h.

__rte_experimental struct rte_stack* rte_stack_create ( const char *  name,
unsigned int  count,
int  socket_id,
uint32_t  flags 
)
Warning
EXPERIMENTAL: this API may change without prior notice

Create a new stack named name in memory.

This function uses memzone_reserve() to allocate memory for a stack of size count. The behavior of the stack is controlled by the flags.

Parameters
nameThe name of the stack.
countThe size of the stack.
socket_idThe socket_id argument is the socket identifier in case of NUMA. The value can be SOCKET_ID_ANY if there is no NUMA constraint for the reserved zone.
flagsAn OR of the following:
  • RTE_STACK_F_LF: If this flag is set, the stack uses lock-free variants of the push and pop functions. Otherwise, it achieves thread-safety using a lock.
Returns
On success, the pointer to the new allocated stack. NULL on error with rte_errno set appropriately. Possible errno values include:
  • ENOSPC - the maximum number of memzones has already been allocated
  • EEXIST - a stack with the same name already exists
  • ENOMEM - insufficient memory to create the stack
  • ENAMETOOLONG - name size exceeds RTE_STACK_NAMESIZE
__rte_experimental void rte_stack_free ( struct rte_stack *  s)
Warning
EXPERIMENTAL: this API may change without prior notice

Free all memory used by the stack.

Parameters
sStack to free
__rte_experimental struct rte_stack* rte_stack_lookup ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice

Lookup a stack by its name.

Parameters
nameThe name of the stack.
Returns
The pointer to the stack matching the name, or NULL if not found, with rte_errno set appropriately. Possible rte_errno values include:
  • ENOENT - Stack with name name not found.
  • EINVAL - name pointer is NULL.