op_pro_mod_objid()
Abstract
Obtains the object ID of the module that owns a process.
Syntax
op_pro_mod_objid (pro_handle)
| Argument | Type | Description |
|---|---|---|
pro_handle |
Prohandle |
Process handle of the process whose owning module is sought |
Return Type
Objid
Object ID of the module that owns the specified process. If an error occurs, the Object ID that is returned will the symbolic constant OPC_OBJID_INVALID.
Example
/* Loop through all the nodes in the system. */
for (i = 0; i < num_nodes; i++)
{
/* Obtain the globally administered node information data */
/* structure for the i_th node. */
ni_ptr = &Tm_Node_Info_Array [i];
/* Obtain a process handle for the "controller" process in the i_th node, */
/* and use it to determine the object id of the controller module. */
cntl_objid = op_pro_mod_objid (ni_ptr->cntl_ph);
/* Test for an error in the object id query. This would result */
/* if the process handle was one obtained as an error or if it */
/* refers to a process that has been destroyed previously. */
if (cntl_objid != OPC_OBJID_INVALID)
{
/* Deliver a packet from the command buffer to each controller. */
pkptr = op_subq_pk_remove (TP_SUBQ_COMMAND, OPC_QPOS_HEAD);
op_pk_deliver (cntl_objid, TP_CNTL_INSTRM_COMMAND);
}
}
Details
Each process is owned by a queue or processor module. This ownership property is set at the time where the process is created. In the case of a module's root process, this occurs when it is created automatically by the Simulation Kernel at the beginning of the simulation. When the root process creates other (child) processes, these become owned by the same module; the same is true for their child processes, and so on.
Generally, op_pro_mod_objid() will be called when processes have generic knowledge of a process handle and need to obtain knowledge of the owning module for the purpose of modifying attributes or communicating with that module. Knowledge of a process handle for a process in another module can be obtained through a number of mechanisms, including shared global variables, and embedding a process handle in a transmitted packet or ICI.
Purpose
op_pro_mod_objid() is typically useful when a process' handle is available to other processes outside its own module. This KP will allow a process to determine the object ID of the owning module, and possibly to use the object ID to obtain the root process of that module via op_pro_root() or to deliver an interrupt of some kind to the remote module, without specifically identifying a process to receive that interrupt. Note, however, that this KP is not useful for determining the object ID of the module that owns the currently executing process, since this can be more easily be obtained by calling the KP op_id_self().
Errors
- Program Abort: Segmentation violation. (due to a malformed process handle)
- Recoverable Error: Process handle is invalid.
- Recoverable Error: Process handle is for destroyed process (
<proc_id>).
Reference
- Use the KP op_id_self() to determine the object id of the module that owns the current process
- Use the KP op_pro_root() to obtain a handle for the root process in a given module
- Use the KP op_ima_obj_attr_get() to obtain attribute values for an object, given its object ID
- Use the KP op_ima_obj_attr_set() to modify attribute values for an object, given its object ID
- Use the KP op_pk_deliver() to deliver a packet to a remote processor or queue module
- Use the KP op_intrpt_force_remote() to force an immediate interrupt at a remote processor or queue