op_subq_pk_swap()
Abstract
Exchanges the packets at the two specified positions within the specified subqueue.
Syntax
op_subq_pk_swap (subq_index, pos_index1, pos_index2)
| Argument | Type | Description |
|---|---|---|
subq_index |
int |
numeric index of the subqueue-of-interest [Subqueue stream indices start at 0 and increment by one. There is no upper bound on the number of subqueues, but conservation of memory is achieved if they are utilized in a contiguous manner. Instead of an explicit index of a subqueue, an abstract subqueue selection index may be specified. An abstract subqueue selection index specifies a particular subqueue by a unique property it has. The acceptable abstract subqueue selection indices are listed in Table 85 “Subqueue Selection Index Symbolic Constants“ on page 26.] |
pos_index1 |
int |
numeric position index within the specified subqueue of one of the packets to be swapped |
pos_index2 |
int |
numeric position index within the specified subqueue of one of the packets to be swapped [See the syntax of op_subq_pk_remove() for more information on the position index arguments.] |
Return Type
void
No return value.
Example
/* get a pointer to the subqueue head */
hd_pkptr = op_subq_pk_access (subq_idx, OPC_QPOS_HEAD);
/* get a pointer to the subqueue tail */
tl_pkptr = op_subq_pk_access (subq_idx, OPC_QPOS_TAIL);
/* obtain wait times */
hd_wait = op_q_wait_time (hd_pkptr);
tl_pkptr = op_q_wait_time (tl_pkptr);
/* compare wait times; if necessary, reshuffle */
if (tl_wait > hd_wait)
op_subq_pk_swap (subq_idx, OPC_QPOS_HEAD, OPC_QPOS_TAIL);
Details
This KP must only be invoked within the context of a process running on a queue module (or from a function which is directly or indirectly invoked by a queue process); invoking it from a process running on a processor, or from a pipeline stage model will cause an error.
Note: If either of the position indices are invalid (i.e., they are less than zero, or larger than the index of the tail packet within the specified subqueue), no swapping will be performed and a recoverable error will occur.
Purpose
Provides a mechanism to swap two packets within a single subqueue. This KP is not used for many applications, but when swapping two packets is necessary, this KP can perform the equivalent of four operations in one invocation (e.g., two packet removals and two packet insertions). Typically, the first two packets on a subqueue are the ones that need to be swapped, when the “head” packet is downgraded below the next packet in terms of priority.
Errors
- Program Abort: KP requires queue context.
- Recoverable Error: Subqueue selection flag (
<flag>) is unrecognized. - Recoverable Error: Swap positions (
<pos_index1>) and/or (<pos_index2>) are invalid.
Reference
- Use the KP op_subq_pk_access() to obtain a pointer to a packet in a subqueue, without removing the packet from the subqueue
- Use the KP op_subq_pk_remove() to remove a packet from a subqueue, and obtain a pointer to it
- Use the KP op_subq_pk_insert() to insert a packet into a subqueue
- Use the KP op_subq_flush() to remove all packets from a subqueue