Package Overview
The Subq (Subqueue) package is a collection of kernel procedures concerned with manipulating a single queueing resource contained within a queue module. Most of the packages documented in this manual are designed for use in three different contexts: by processes executing on processors, by processes executing on queues, and by Transceiver Pipeline stages. The Subq package is specialized in that it can only be used in one context: by processes executing on queues.
The internal resources of a queue 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 package 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_subq_empty() can be used by a queue process to determine if one of its subqueues is empty. It returns the value 1 if the specified subqueue is empty, or 0 if the specified subqueue is not empty.
Subqueues collect a large number of statistics, to provide detailed information about subqueue usage patterns. The KP op_subq_stat() can be used to obtain the value of a built-in subqueue statistic; the statistic is specified by a symbolic constant which represents an integer code.
Subqueues can be identified by a specific numeric index. For instance, if there are four subqueues, they are given the indices 0, 1, 2, and 3. There is another way of identifying subqueues, based on abstract selection metrics that are specified by special symbolic constants. For instance, if a queueing process needs to specify the subqueue that contains the most packets, it can identify it using the constant OPC_QSEL_MAX_PKSIZE; similarly, if a queueing process needs to specify the subqueue which contains the least number of bits, it can identify it using the constant OPC_QSEL_MIN_BITSIZE. There are twenty-one abstract subqueue indices, listed in Table 85 “Subqueue Selection Index Symbolic Constants“ on page 26. All Subq KPs that accept a subqueue index argument will properly handle abstract subqueue indices. The KP op_subq_index_map() converts an abstract subqueue index into a specific numeric subqueue index.
During the debugging process for queueing process models, it is useful to see the changing state of a subqueue’s contents. This can be achieved by using the KP op_subq_print(), which prints out the contents of a subqueue (i.e., a list of the packets contained within) onto the standard output device.
Each packet stored in a subqueue has a priority value associated with it; this value can be accessed using the two Pk package KPs op_pk_priority_get() and op_pk_priority_set(). If all the packets in a subqueue have been assigned priority values, the subqueue can be sorted according to the priority of the packets within it. The KP op_subq_sort() performs the sorting operation on the specified subqueue; higher priority packets are placed near the head of the subqueue and lower priority packets are placed near the tail of the subqueue.
Certain global or local events in a network necessitate the emptying (or “flushing”) of a subqueue. An example is a global message that informs queues that a particular class of packet is no longer valid. When a queueing process determines that it needs to flush all the packets in a particular subqueue, the KP op_subq_flush() can be invoked.
The most basic operations on subqueues are inserting, removing, or “peeking” at packets. Each of these operations manipulates a single packet at a time. The KP op_subq_pk_insert() inserts a packet at a specified location in a subqueue. The KP op_subq_pk_remove() removes a packet from a specified location in a subqueue, returning a pointer to the packet for use by the queueing process. The KP op_subq_pk_access() also returns a pointer to a packet at a specified location in a subqueue, but does not affect the status of the packet within the subqueue. Subqueue positions are identified by numeric indices; the index 0 indicates the head of a subqueue, with increasing positive indices associated with successive packets towards the tail of the subqueue. In addition to the strict positional indices, there are three symbolic constants that can be used as “abstract” position indices. These constants conveniently indicate the subqueue head (OPC_QPOS_HEAD), subqueue tail (OPC_QPOS_TAIL), or the appropriate location based on packet priority (OPC_QPOS_PRIO), and can be used anywhere subqueue positions are expected.
It is sometimes useful to take two packets within a subqueue, and swap their locations. This can be accomplished by the KP op_subq_pk_swap().