Fast Queue API

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. The function yields the CPU for a few cycles by executing a long latency instruction when the queue is full.

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. The function yields the CPU for a few cycles by executing a long latency instruction when the queue is empty.

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_enqueue_noyield`

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_noyield(queue,node)

Parameters

queue - Queue selected for dequeue.

node - Pointer to the node to enqueue.

Return Values

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

`fastq_dequeue_noyield`

Description

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

Function

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