op_subq_sort()
Abstract
Sorts the specified subqueue according to the priority property associated with each packet.
Syntax
op_subq_sort (subq_index)
| 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.] |
Return Type
void
No return value.
Example
/* determine the type
of the interrupt */
if (op_intrpt_type () == OPC_INTRPT_REMOTE)
{
/* cold reboot: total loss of queued packets */
if (op_intrpt_code () == COLD_REBOOT)
{
/* record the number of packets lost */
num_lost_packets += op_q_stat (OPC_QSTAT_PKSIZE);
/* flush the queue of its contents */
op_q_flush ();
}
/* prioritize: loop through and sort all subqueues */
else if (op_intrpt_code () == PRIORITIZE)
{
op_ima_obj_attr_get (op_id_self (), "subqueue", &subq_objid);
num_subqs = op_topo_child_count (subq_objid, OPC_OBJTYPE_SUBQ);
for (i = 0; i < num_subqs; i++)
op_subq_sort (i);
}
}
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.
Purpose
Provides a mechanism to sort a subqueue, based on the priority property of packets, in one invocation. In priority queueing scenarios, subqueues are typically always in the sorted state. This means that packets are inserted by passing the OPC_QPOS_PRIO symbolic constant to the KP op_subq_pk_insert(). Such scenarios do not require the invocation of this KP. However, op_subq_sort() is useful when a previously unsorted queue changes status and must suddenly become prioritized. Another application of this KP occurs when certain packets in a sorted subqueue have their priority levels dynamically changed, thus requiring a reshuffling of the subqueue.
Errors
- Program Abort: KP requires queue context.
- Recoverable Error: Subqueue selection flag (
<flag>) is unrecognized. - Program Abort: Segmentation violation. (due to a malformed packet within the subqueue)
Reference
- Use the KP op_pk_priority_get() to obtain the priority value of a packet
- Use the KP op_pk_priority_set() to assign a new priority value to a packet
- Use the KP op_subq_pk_insert(), with the symbolic constant OPC_QPOS_PRIO passed as the position index, to insert a packet into a subqueue while maintaining priority ordering
- Use the KP op_subq_pk_swap() to swap the positions of two packets in a subqueue