op_subq_flush()
Abstract
Flushes the specified subqueue, destroying any packets it contains.
Syntax
op_subq_flush (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
subq_index = get_subq_index_from_connection (cur_connection_ptr);
if (connection_aborted_flag)
{
/* This connection is terminated. */
if (op_subq_empty (subq_index) == OPC_FALSE)
{
/* Subqueue contains messages queued for processing. */
/* Flush the subqueue of messages. */
op_subq_flush (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 from 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 remove all the packets in a subqueue. The packets are destroyed in the process, so this operation is only used when the packets in the subqueue can be dropped due to some dynamic condition. Typical modeling applications that call for flushing a subqueue include node crashes or reboots, links or link interfaces going down, routing or other network management updates that invalidate currently buffered data, and the closing of a virtual circuit or session with no requirement to deliver currently buffered messages.
Errors
- Program Abort: KP requires queue context.
- Recoverable Error: Subqueue selection flag (
<flag>) is unrecognized. - Program Abort: Segmentation violation. (due to the presence in the queue of malformed packets or malformed structure or packet fields within the enqueued packets)
Reference
- Use the KP op_q_flush() to flush all subqueues in the surrounding queue
- Use the KP op_subq_empty() to determine if a subqueue is empty of packets
- 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 single packet from a subqueue, and obtain a pointer to it