rte_stack.h File Reference

#include <stdalign.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"
#include "rte_stack_pile.h"

Go to the source code of this file.

Macros
#define	RTE_STACK_NAMESIZE
#define	RTE_STACK_F_LF   0x0001
#define	RTE_STACK_F_PILE   0x0002

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

Detailed Description

RTE Stack.

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

RTE_STACK_NAMESIZE

#define RTE_STACK_NAMESIZE

Value:

               (RTE_MEMZONE_NAMESIZE - \
               sizeof(RTE_STACK_MZ_PREFIX) + 1)

The maximum length of a stack name.

Definition at line 29 of file rte_stack.h.

RTE_STACK_F_LF

#define RTE_STACK_F_LF   0x0001

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

Definition at line 137 of file rte_stack.h.

RTE_STACK_F_PILE

#define RTE_STACK_F_PILE   0x0002

The stack-like pile uses lock-free push and pop functions. It is optimized for bulks of objects, and is not strictly LIFO, and is not strictly bounded by its size, but might hold more objects. This flag is only supported on x86_64 or arm64 platforms, currently.

Warning

EXPERIMENTAL: this API may change, or be removed, without prior notice.

Definition at line 148 of file rte_stack.h.

Function Documentation

__rte_aligned()

struct __rte_aligned

(

16

)

< Stack top

< Modification counter for avoiding ABA problem

Definition at line 56 of file rte_stack.h.

rte_stack_push()

static __rte_always_inline unsigned int rte_stack_push ( struct rte_stack *  s, void *const *  obj_table, unsigned int  n  )

static

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

Parameters

s	A pointer to the stack structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The 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 171 of file rte_stack.h.

rte_stack_pop()

static __rte_always_inline unsigned int rte_stack_pop ( struct rte_stack *  s, void **  obj_table, unsigned int  n  )

static

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

Parameters

s	A pointer to the stack structure.
obj_table	A pointer to a table of void * pointers (objects).
n	The number of objects to pull from the stack.

Returns

Actual number of objects popped (either 0 or n).

Definition at line 197 of file rte_stack.h.

rte_stack_count()

static __rte_always_inline unsigned int rte_stack_count ( struct rte_stack *  s )

static

Return the number of used entries in a stack.

Parameters

s	A pointer to the stack structure.

Returns

The number of used entries in the stack.

Definition at line 219 of file rte_stack.h.

rte_stack_free_count()

static __rte_always_inline unsigned int rte_stack_free_count ( struct rte_stack *  s )

static

Return the number of free entries in a stack.

Parameters

s	A pointer to the stack structure.

Returns

The number of free entries in the stack.

Definition at line 240 of file rte_stack.h.

rte_stack_create()

struct rte_stack * rte_stack_create	(	const char *	name,
		unsigned int	count,
		int	socket_id,
		uint32_t	flags
	)

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

name	The name of the stack.
count	The size of the stack.
socket_id	The 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.
flags	An 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
• ENOTSUP - platform does not support given flags combination.

rte_stack_free()

void rte_stack_free

(

struct rte_stack *

s

)

Free all memory used by the stack.

Parameters

s	Pointer to stack created with rte_stack_create(). If s is NULL, no operation is performed.

rte_stack_lookup()

struct rte_stack * rte_stack_lookup

(

const char *

name

)

Lookup a stack by its name.

Parameters

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