op_subq_pk_access()
Abstract
Obtains a pointer to a packet stored in the specified subqueue, at the specified subqueue position.
Syntax
op_subq_pk_access (subq_index, pos_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.] |
pos_index |
int |
numeric position index within the subqueue where the packet to be accessed is located [Position indices start at 0 at the head of the queue, and increment by one until the tail is reached. Instead of an explicit position index, an abstract subqueue position index may be specified (see Table 84 “Subqueue Position Index Symbolic Constants“ on page 25); acceptable values are OPC_QPOS_HEAD, OPC_QPOS_TAIL, and OPC_QPOS_PRIO.] |
Return Type
Packet*
Pointer to the packet accessed within the specified subqueue. The special value represented by symbolic constant OPC_NIL will be returned if the specified position index is larger than the index of the tail packet in the specified subqueue.
Example
/* determine if queue is empty; if not, then process its contents */
if (op_q_empty () == OPC_FALSE)
{
/* determine the number of subqueues */
op_ima_obj_attr_get (op_id_self (), "subqueue", &subq_objid);
num_subqs = op_topo_child_count (subq_objid, OPC_OBJTYPE_SUBQ);
/* loop through each subqueue */
for (q_index = 0; q_index < num_subqs; q_index++)
{
/* determine the number of packets in subqueue */
num_pkts = op_subq_stat (q_index, OPC_QSTAT_PKSIZE);
/* loop through each packet in subqueue */
for (j = 0; j < num_pkts; j++)
{
/* schedule self interrupt based on packet’s insert time */
pkptr = op_subq_pk_access (q_index, j);
op_intrpt_schedule_self (op_q_insert_time (pkptr) + 0.05, PROC_COMP);
}
}
}
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 them from a process running on a processor, or from a pipeline stage will cause an error.
If the value specified for the argument pos_index is not one of the supported symbolic constants OPC_QPOS_PRIO, OPC_QPOS_HEAD, or OPC_QPOS_TAIL, and the value is less than zero then this KP will access the packet at the head of the subqueue. Similarly if <pos_index> is greater than or equal to the number of packets in the subqueue, this KP will access the packet at the tail end of the subqueue.
Purpose
Provides a mechanism to obtain the pointer to a packet contained within a subqueue. Typically this is used to scan the contents of a subqueue, looking for a particular packet (or type of packet). Scanning can be implemented by first determining the number of packets in a subqueue via the KP op_subq_stat() called with the argument OPC_QSTAT_PKSIZE. A loop can be setup which obtains the pointer to each packet in the subqueue by calling op_subq_pk_access(). Once a packet’s pointer is obtained, any of its properties can be used to implement sophisticated queueing algorithms, including: size (either total, bulk data, or field), creation time, stamp time, insert time, wait time, field contents, priority, etc.
Errors
- Program Abort: KP requires queue context.
- Recoverable Error: Subqueue selection flag (
<flag>) is unrecognized.
Reference
- 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_pk_swap() to swap two packets in a subqueue
- Use the KP op_subq_flush() to remove all packets from a subqueue