op_pk_priority_set()
Abstract
Assigns the specified priority value to the priority property of the specified packet.
Syntax
op_pk_priority_set (pkptr, value)
| 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().] |
value |
double |
priority value for the specified packet [This is a user-defined value that can take on any value permitted by the double data type. Higher values have higher priority.] |
Return Type
void
No return value.
Example
Excerpt from: example model (models/std/base); process model (acb_fifo_ms); state (arrival); enter execs.
/* acquire the arriving packet */
/* multiple arriving streams are supported. */
pkptr = op_pk_get (op_intrpt_strm ());
/* new packets are stamped to */
/* indicate the packet is waiting for service. */
op_pk_priority_set (pkptr, PK_STATUS_WAITING);
/* attempt to enqueue the packet at tail of subqueue 0 */
if (op_subq_pk_insert (0, pkptr, OPC_QPOS_TAIL) != OPC_QINS_OK)
{
/* the insertion failed (due to a full queue)... */
op_pk_destroy (pkptr);
/* set flag indicating insertion failed... */
insert_ok = 0;
}
Details
The priority property of a packet can be modified or accessed at any time. Prior to being set by this KP, the default value of a packet’s priority property is set to the special value which is represented by the symbolic constant OPC_PRIO_NOT_SET. Both unformatted and formatted packets can be operated on via this KP.
Purpose
Provides a mechanism to associate a priority value with a packet, without using any of the normal fields within the packet. Typically, this priority value is used as a guide for sorting subqueues, or inserting new packets into a presorted subqueue and maintaining the sorted ordering. These operations are supported by KPs in the Subq package, as mentioned in the Reference section. However, since the priority property has a user-defined meaning, and since KPs exist to set and get this property, it can be used for many identification and discrimination applications in processes.
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.
- Program Abort: Packet pointer references unowned packet (
<pk_id>).
Reference
- Use the KP op_pk_priority_get() to obtain a packet’s priority property
- Use the KP op_subq_pk_insert(), with the pos_index argument set to the symbolic constant OPC_QPOS_PRIO, to insert a packet into a subqueue using the priority property as a guide for determining the insertion point (this requires the subqueue to be presorted according to packet priorities)
- Use the KP op_subq_sort() to sort a queue according to the priority property of packets it contains