op_pro_root()
Abstract
Obtains a handle for the root process of a queue or processor module, given the module’s object ID.
Syntax
op_pro_root (mod_objid)
| Argument | Type | Description |
|---|---|---|
mod_objid |
Objid |
Object ID of the queue or processor module whose root process is sought |
Return Type
Prohandle
Process handle for the root process of the module whose object ID is given. This process handle will be invalid if the module object ID that is supplied causes an error. An invalid process ID can be detected by calling the KP op_pro_valid().
Example
/* If the current interrupt is a stream interrupt, accept the arriving packet. */
if (op_intrpt_type () == OPC_INTRPT_STRM)
{
pkptr = op_pk_get (op_intrpt_strm ());
/* This module only receives packets via packet delivery. */
/* Determine the object id of the module that sent the packet. */
src_objid = op_intrpt_source ();
/* This module is necessarily a queue or processor; determine its root process. */
sender_root_ph = op_pro_root (src_objid);
/* Send an acknowledgment in the form of a process interrupt. Use one */
/* standard propagation delay to emulate the travel time for the ack. */
op_intrpt_schedule_process (sender_root_ph, op_sim_time () +
std_prop_delay, ACK);
}
Details
Every queue or processor module has at least one process active within it. This is the root process that is created by the Simulation Kernel at the start of the simulation and whose type is specified by the process model attribute of the module. This process cannot be destroyed or replaced in its role as root.
The root process’ process handle can be obtained by calling the KP op_pro_root() if the object ID of the module of interest is known. This object ID can be obtained in a number of ways depending upon a model’s configuration. See the KPs of the Id and Topo packages for more on this topic.
This KP must be called with the object ID of a module that is a processor or queue. Otherwise a recoverable error will be generated and an invalid event handle will be returned. Therefore, if there is any doubt about the type of object that the object ID refers to, it should be first tested with op_id_to_type() to verify that it is usable.
A process may determine if it is the root of its own module by calling op_pro_root() and op_pro_self(); the two process handles thus obtained may be compared via the KP op_pro_id(), an equality indicating that the process is the root.
Purpose
This KP allows an arbitrary process or user-defined function to obtain a handle for the root process that resides in a specified queue/processor module. This is useful for a process to determine the root in its own module as well as to determine if it is itself the root. It is also sometimes useful to determine the root process of another module in order to establish direct communications with it, thus bypassing any interrupt redirections that may have been established at that module via op_intrpt_port_register() or op_intrpt_type_register().
Errors
- Recoverable Error: Object ID (
<mod_objid>) is invalid. - Recoverable Error: Object (
<mod_objid>) has incorrect type; queue or processor objects are expected. - Recoverable Error: Object ID (
<objid>) refers to a restricted object.
Reference
- Use the KP op_id_self () to obtain the object ID for the currently executing process
- Use the KP op_pro_id() to obtain the unique integer identifier of a process
- Use the KP op_pro_invoke() to cause a process to execute immediately
- Use the KP op_intrpt_schedule_process() to schedule a future interrupt for a process