Package Overview

The Q (Queue) package is a collection of kernel procedures concerned with manipulating the queueing resources that are contained within queue modules. Most of the packages documented in this manual are designed for use in four different contexts: by processes executing on processors, by processes executing on queues, by Transceiver Pipeline stages, and by procedure calls scheduled via the KP op_intrpt_schedule_call(). The Q package is specialized in that it can only be used in one context: by processes executing on queues.

A queue’s internal resources are organized into a bank of subqueues. Each subqueue is a separate linked list of packets, with an identified head and tail. The Subq package supports operations on subqueues, such as inserting and extracting packets. The Q package supports operations on the bank of subqueues as a whole, so individual subqueues are not specified in Q operations.

A subqueue is empty if it does not contain any packets; a queue is empty if all of its subqueues are empty. The KP op_q_empty() can be used by a queue process to determine if the queue is empty.

Certain global or local events in a network necessitate the emptying (or “flushing”) of a queue. Examples are a global message that informs queues that the network protocols are being reset, or a crash of the local node. When a queue process determines that it needs to flush all packets, the KP op_q_flush() can be invoked.

Queue modules collect a large number of statistics, both at the subqueue and queue levels. Queue-level statistics are aggregate values based on the operation of all subqueues. The KP op_q_stat() can be used to obtain the value of a built-in queue-level statistic; the statistic is specified by an integer code (symbolic constants for all supported queue statistics appear in Chapter 28 “Symbolic Constants” on page 1).

Packets which are stored in queues contain special properties which keep track of the time at which they entered the queueing resource, and the amount of time they have been waiting inside the queueing resource. The insert time property of a packet can be obtained via the KP op_q_insert_time(), and the waiting time property of a packet can be obtained via the KP op_q_wait_time().