op_q_wait_time()
Abstract
Obtains the amount of time a packet has spent “waiting” inside the subqueue that currently contains it.
Syntax
op_q_wait_time (pkptr)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest [A pointer to a packet can be obtained from many KPs, but in this context the most common sources are op_subq_pk_access() and op_subq_pk_remove().] |
Return Type
double
Amount of time the specified packet has spent inside its current subqueue within the surrounding queue. The constant OPC_TIME_INVALID will be returned if a recoverable error occurs.
Example
/* determine if queue is empty; if not, then process its contents */
if (!op_q_empty ())
{
/* determine the number of subqueues */
num_subqs = op_topo_child_count (op_id_self (), OPC_OBJTYPE_SUBQ);
/* loop through each subqueue */
for (i = 0; i < num_subqs; i++)
{
/* determine the number of packets in subqueue */
num_pkts = op_subq_stat (i, OPC_QSTAT_PKSIZE);
/* loop through each packet in subqueue */
for (j = 0; j < num_pkts; j++)
{
/* schedule self interrupt based on packet’s wait time */
pkptr = op_subq_pk_access (i, j);
op_intrpt_schedule_self (1.0 - op_q_wait_time (pkptr), PROC_COMP);
}
}
}
Details
Q package KPs 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, a pipeline stage model, or a function scheduled via op_intrpt_schedule_call() will cause an error.
This KP should only be applied to packets currently contained within a subqueue of the surrounding queue. Packets which have been extracted from a subqueue, or which have yet to be inserted into a subqueue, or which are merely stored in state variable pointers of the queue process, will cause an error if this KP is applied to them.
The waiting time of a packet is reset whenever the packet is removed from a subqueue and reinserted. The following scenario depicts this reset phenomenon:
- a packet enters a subqueue input stream at T = 5
- the packet is inserted into a subqueue at T = 5
- at T = 8, this KP is applied to the packet, and it returns the value 3
- at T = 10, the packet is removed from the subqueue, temporarily stored in a state variable, and then reinserted into another subqueue
- at T = 11, this KP is applied to the packet, and it returns the value 1
Purpose
Provides a mechanism to determine the amount of time the specified packet has been stored in a subqueue within the surrounding queue. This is typically useful for determining the relative urgency of processing a time critical packet, or the amount of time remaining for a fixed delay queueing system.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet (
<pk_id>). - Program Abort: Packet pointer references unowned packet (
<pk_id>). - Recoverable Error: packet (
<pk_id>) is not currently enqueued.
Reference
- Use the KP op_q_insert_time() to determine the time when a packet was inserted into its current subqueue
- Use the KP op_q_stat() to obtain the value of queue-related statistics
- Use the KP op_subq_stat() to obtain the value of subqueue-related statistics