op_subq_pk_remove()

Abstract

Obtains a pointer to a packet stored in the specified subqueue at the specified position, and removes the packet from the subqueue.

Syntax

op_subq_pk_remove (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 removed 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 removed from the specified subqueue. The constant OPC_NIL will be returned if a recoverable error occurs.

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 it 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().

If a position index is specified that is negative (and not one of the supported symbolic constants), or greater than or equal to the number of packets in the queue, a recoverable error will occur and the constant OPC_NIL will be returned.

Purpose

Provides a mechanism for removing a packet from a subqueue. This is the only way that packets can non-destructively leave a subqueue (i.e., there is no automatic mechanism in the Simulation Kernel for packets to flow out of a subqueue). The only other way for packets to leave a subqueue is via the destructive KPs op_subq_flush() and op_q_flush(). Even the supplied base queueing models explicitly pull packets from subqueues using this KP. The position index argument allows flexibility in determining which packet should be removed; it can be a concrete numeric position (including the conveniently specified head or tail positions), or a position determined by a packet’s priority (in which case the highest priority packet is removed from the subqueue, whichever position it occupies).

Errors

  • Program Abort: KP requires queue context.
  • Recoverable Error: Subqueue selection flag (<flag>) is unrecognized.
  • Recoverable Error: Position (<pos_index>) is out-of-range for subq (<subq_index>).

Reference

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com