op_pk_tree_id()
Abstract
Obtains the identifier for the “tree” of packets that the specified packet belongs to. A tree of packets is the set of packets that result from duplication of the same original packet.
Syntax
op_pk_tree_id (pkptr)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet of interest. [A pointer to a packet can be obtained from many KPs, including op_pk_create(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
Return Type
OpT_Packet_Id
Integer value that identifies the “tree” of packets that the specified packet belongs to.
Example
/* Obtain the next control message. Control messages are processes in LIFO order. */
ctrl_pkptr = op_subq_pk_remove (CTRL_SUBQ, OPC_QPOS_TAIL);
/* Extract the control message’s instruction type and process accordingly. */
op_pk_fd_get (ctrl_pkptr, "instruction", &ctrl_inst);
switch (ctrl_inst)
{
case CTRL_INST_RECALL:
/* All data packet’s that are copies of a particular original are to be */
/* discarded. Obtain the "tree ID" that identifies this class of packets. */
op_pk_fd_get (ctrl_pkptr, "tree_id", &recall_tree_id);
/* Search for data packets that should be removed from data message queue. */
q_size = op_q_stat (OPC_QSTAT_PKSIZE);
for (i = 0; i < q_size; i++)
{
/* Extract the i_th packet and obtain its tree ID; */
/* decide whether to delete */
data_pkptr = op_subq_pk_access (DATA_SUBQ, i);
if (op_pk_tree_id (data_pkptr) == recall_tree_id)
{
op_pk_destroy (op_subq_pk_remove (DATA_SUBQ, i--));
i--;
Details
A new tree ID is generated whenever a new, original packet is created. New, original packets are created by calls to the KPs op_pk_create() or op_pk_create_fmt(). Other operations that may cause packets to be created, but not original packets, are the KP op_pk_copy() and transmission of packets via radio or bus links. It is the set of all packets that are the copies of a single original together with the original packet itself that form a packet tree. Each tree is assigned a tree ID by marking new original packets with a unique integer. The tree is maintained as a loose association of packets simply by transferring this identifier to copies as they are generated. That is, copies of copies carry the same tree-id as well.
Note that when a packet is copied, packets that are encapsulated within it are copied as well, and such packets have tree IDs that are the same as the corresponding original encapsulated packets.
Packet IDs, which are unique to each individual packet instance that is created within a simulation run and are obtainable via the KP op_pk_id(), are maintained entirely independently from tree IDs; while two packets may have the same tree ID, no two packets ever have the same packet ID. When all packets with a particular tree ID have been destroyed, the tree ID will never again be assigned to any new packets that enter circulation.
Purpose
This KP allows packets that result from packet duplication to be linked to the packet from which they originated. This is particularly useful for packet tracing that is performed on an end-to-end basis, after duplication for retransmission or broadcasting has occurred. For example, when a packet transmission request is initiated by a application-level process, it is possible that the submitted packet will be copied several times at lower protocol layers, and in particular, at the physical layer when using a broadcast medium such as a bus or radio link. Thus when the packet finally reaches its destination, it is in reality a new instance of the original packet and the value returned by op_pk_id() will be different for this packet than for the original. However, the tree ID returned by op_pk_tree_id() will be identical.
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer or malformed packet)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
Reference
- Use the KP op_pk_id() to obtain an identifier that is unique to each individual packet.
- Use the KP op_pk_copy() to create a copy of an existing packet.