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
- Use the KP op_subq_pk_access() to obtain a pointer to a packet in a subqueue, without removing the packet from the 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_pk_swap() to swap two packets in a subqueue
- Use the KP op_subq_flush() to remove all packets from a subqueue