C H A P T E R 5

Fast Queue API

This chapter describes the Fast Queue API functions. Topics include:

Fast Queue API Introduction

Fast Queue API Function Descriptions

Fast Queue API Introduction

The Fast Queue API provide a facility where threads can exchange or pass data in a first-in-first-out (FIFO) order. This API provides routines for creating and using fast queues, a fast communication mechanism between two or more threads. The fast queues are based on circular buffers and is an advantage over teja queues that are for one consumer and one producer. The fast queues are poll-driven and are more efficient for high packet rates. The fast queue API is not thread safe and need to be protected with locks when they are used by more than one consumer or producer.

The API functions are defined in fastq.h located in the src/dev/net/include directory of the SUNWndps package.

Fast Queue API Function Descriptions

`fastq_create`

Description

This function creates a new instance of the fast queue.

Function

fastq_t fastq_create(size_t size)

Parameters

size - Size of the queue. Required size is the power of 2.

Return Values

`fastq_t` - Returns a fast queue instance or `NULL` if it fails.

`fastq_enqueue`

Description

This function enqueues a node pointer into the fast queue. If -1 is returned, the queue is either full or some other error has occurred.

Function

`fastq_enqueue(`queue`,` node`)`

Parameters

queue - Queue to enqueue to.

node - Pointer to the node to enqueue.

Return Values

`int` - Returns `0` if successful or `-1` if it fails.

`fastq_dequeue`

Description

This function dequeues a pointer to a node from the queue.

Function

fastq_dequeue(queue)

Parameters

queue - Queue selected for dequeue.

Return Values

`void` * - Returns a pointer to the dequeued node or `NULL` if the queue is empty.

`fastq_get_size`

Description

This function returns a value which is the depth of the queue at a given point of time.

Function

fastq_get_size(queue)

Parameters

queue - Queue requested to obtain size.

Return Values

`int` - Returns the number of elements in the queue or 0 if empty.

`fastq_is_empty`

Description

This function checks if the queue is empty.

Function

fastq_is_empty(queue)

Parameters

queue - Queue selected to test.

Return Values

`int` - Returns `1` if the queue is empty or `0` if the queue is not empty.

`fastq_is_full`

Description

This function checks if the queue is full.

Function

fastq_is_full(queue)

Parameters

queue - Queue selected to test.

Return Values

`void` * - Returns `1` if the queue is full or `0` if the queue is not full.

Fast Queue API Introduction

Fast Queue API Function Descriptions

fastq_create

Description

Function

Parameters

size - Size of the queue. Required size is the power of 2.

Return Values

fastq_t - Returns a fast queue instance or NULL if it fails.

fastq_enqueue

Description

Function

fastq_enqueue(queue, node)

Parameters

queue - Queue to enqueue to.

node - Pointer to the node to enqueue.

Return Values

int - Returns 0 if successful or -1 if it fails.

fastq_dequeue

Description

Function

Parameters

queue - Queue selected for dequeue.

Return Values

void * - Returns a pointer to the dequeued node or NULL if the queue is empty.

fastq_get_size

Description

Function

Parameters

queue - Queue requested to obtain size.

Return Values

int - Returns the number of elements in the queue or 0 if empty.

fastq_is_empty

Description

Function

Parameters

queue - Queue selected to test.

Return Values

int - Returns 1 if the queue is empty or 0 if the queue is not empty.

fastq_is_full

Description

Function

Parameters

queue - Queue selected to test.

Return Values

void * - Returns 1 if the queue is full or 0 if the queue is not full.

`fastq_create`

`fastq_t` - Returns a fast queue instance or `NULL` if it fails.

`fastq_enqueue`

`fastq_enqueue(`queue`,` node`)`

`int` - Returns `0` if successful or `-1` if it fails.

`fastq_dequeue`

`void` * - Returns a pointer to the dequeued node or `NULL` if the queue is empty.

`fastq_get_size`

`int` - Returns the number of elements in the queue or 0 if empty.

`fastq_is_empty`

`int` - Returns `1` if the queue is empty or `0` if the queue is not empty.

`fastq_is_full`

`void` * - Returns `1` if the queue is full or `0` if the queue is not full.