op_subq_empty()
Abstract
Determines if the specified subqueue is empty of packets.
Syntax
op_subq_empty (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
Boolean
Boolean value indicating whether the specified subqueue is empty. The returned value is OPC_TRUE if the specified subqueue is empty; OPC_FALSE otherwise.
Example
Excerpt from: example model (models/std/base); process model (pf_fifo); state (SEND_HEAD); enter execs.
/* a request has been made to forward a packet */
/* over one of the queue’s output streams */
/* the packet will be pulled from the subqueue */
/* with the same index as the output stream */
/* determine which subqueue is being accessed */
subq_index = op_intrpt_code ();
/* check if it is empty */
if (op_subq_empty (subq_index) == OPC_FALSE)
{
/* access the first packet in the subqueue */
pkptr = op_subq_pk_remove (subq_index, OPC_QPOS_HEAD);
/* forward it to the destination over requested stream */
/* use ’quiet’ mode to avoid causing a stream interrupt. */
op_pk_send_quiet (pkptr, subq_index);
}
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 a pipeline stage will cause an error.
A subqueue is initially empty. Packets are added to it via the KP op_subq_pk_insert(), and they are removed via the KPs op_subq_pk_remove(), op_subq_flush(), or op_q_flush().
Purpose
Provides a mechanism to determine if a subqueue is empty. This KP is usually invoked as a conditional in a process FSM, or in the conditional clause of an if statement, to bracket a group of statements that should only be executed if a particular subqueue contains packets. Typically the bracketed statements will attempt to process one or more of the packets in the subqueue, removing them via the KP op_subq_pk_remove().
Errors
- Program Abort: KP requires queue context.
- Recoverable Error: Subqueue selection flag (
<flag>) is unrecognized.
Reference
- Use the KP op_q_empty() to determine if all subqueues in the surrounding queue are empty
- Use the KP op_subq_stat(), with the
OPC_QSTAT_PKSIZEsymbolic constant as an argument, to determine the number of packets contained in a 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_flush() to remove all the packets from a subqueue