op_subq_pk_insert()

Abstract

Inserts the specified packet into the specified subqueue, at the specified position.

Syntax

op_subq_pk_insert (subq_index, pkptr, 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. 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.]
pkptr Packet* pointer to the packet-of-interest
pos_index int numeric position index within the subqueue where the specified packet is to be inserted [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

int

Insertion code which indicates whether the insertion operation completed successfully. This numeric code can be compared to the following symbolic constants: OPC_QINS_OK, OPC_QINS_FAIL, OPC_QINS_PK_ERROR, OPC_QINS_SEL_ERROR; for more information, see Table 83 “Subqueue Insertion Code Symbolic Constants“ on page 25.

Example

Excerpt from: example model (models/std/fddi); process model (fddi_mac); state (ENCAP); enter execs.

/* Compose a mac frame from all these elements */
mac_frame_ptr = op_pk_create_fmt ("fddi_mac_fr");
op_pk_nfd_set (mac_frame_ptr, "svc_class", svc_class);
op_pk_nfd_set (mac_frame_ptr, "dest_addr", dest_addr);
op_pk_nfd_set (mac_frame_ptr, "src_addr", my_address);
op_pk_nfd_set (mac_frame_ptr, "info", pdu_ptr);
if (svc_class == FDDI_SVC_ASYNC)
	{
	op_pk_nfd_set (mac_frame_ptr, "tk_class", req_tk_class);
	op_pk_nfd_set (mac_frame_ptr, "pri", req_pri);
	}
/* Assign the frame control field... */
op_pk_nfd_set (mac_frame_ptr, "fc", FDDI_FC_FRAME);

/* Enqueue the frame at the tail of the queue. */
op_subq_pk_insert (0, mac_frame_ptr, OPC_QPOS_TAIL);

Details

If the value specified for 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, this KP will insert 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 insert the packet at the tail end of the subqueue.

If the value of pos_index is OPC_QPOS_PRIO, the packet is inserted according to its priority (as assigned using op_pk_priority_set()). Higher priority packets are inserted closer to the head of the subqueue than lower priority ones; packets with no assigned priority (OPC_PRIO_NOT_SET) come last. For example, a packet with priority 10.0 will be inserted ahead of one with priority 5.0, but behind one with priority 20.0. If one or more packets with the same priority exist in the subqueue, the new packet will be inserted immediately behind them.

Note: The subqueue must be sorted by priority (using op_subq_sort()) before you can insert packets using OPC_QPOS_PRIO.

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

Because subqueues can be limited in terms of the quantity of packets or bits they can hold, this KP can fail in its goal of inserting the specified packet (see the Errors section below). When this type of failure occurs, the packet’s status is unaffected and the process has flexibility as to how to handle the situation (for example, destroying the packet, sending it back to the source, etc.).

Purpose

Provides a mechanism for inserting a packet into a subqueue. This is the only way that packets can enter a subqueue (i.e., there is no automatic mechanism in the Simulation Kernel for packets to enter a subqueue). Even the supplied base queueing models must explicitly pull packets from their input streams and insert them into subqueues using this KP. The position index argument allows flexibility in determining where the specified packet should be inserted; it can be a concrete numeric position (including the conveniently specified head or tail positions), or a position determined by the packet’s priority property relative to other packets.

Errors

  • Program Abort: KP requires queue context.
  • Program Abort: Packet pointer is NIL.
  • Program Abort: Packet pointer references destroyed packet.
  • Program Abort: Packet pointer references static packet.
  • Program Abort: Segmentation violation. (due to a malformed packet)
  • Recoverable Error: Subqueue selection flag (<flag>) is unrecognized. (in this case the special constant OPC_QINS_SEL_ERROR is returned)
  • Recoverable Error: Packet (<pk_id>) is already enqueued in subqueue (<subq_index>). (in this case the special constant OPC_QINS_PK_ERROR is returned)

Note: The constant OPC_QINS_FAIL is returned if packet insertion fails because there is insufficient storage capacity in the queue or subqueue; however, this is not considered an error.

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