op_pro_invoke()
Abstract
Invokes a process in the context of the current event and current module. The calling process is suspended until this KP returns.
Syntax
op_pro_invoke (pro_handle, argmem_ptr)
| Argument | Type | Description |
|---|---|---|
pro_handle |
Prohandle |
Process handle of the process to be invoked |
argmem_ptr |
void* |
Address of argument memory block to be made available to the invoked process via op_pro_argmem_access(). OPC_NIL if argument memory is not used. |
Return Type
Compcode
Completion code indicating if the invocation was successfully carried out. The calling process can compare this code against the constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE. Reasons for failure include a stale process handle and invocation of a process owned by another module.
Example
Excerpt from: example model (models/std/x25); process model (x25_dte_root); state (r1); exit execs.
/* Create the new channel. */
chan_ptr = x25_channel_create (channel_root, i);
chan_ptr->permanent = 0;
/* Initialize its address information and stream indices. */
x25_channel_init (chan_ptr, local_addr, remote_addr, X25C_DTE_DL_OUTSTRM, pk_strm);
/* Create the process for this channel. Share the channel data structure with it. */
chan_ptr->process = op_pro_create ("x25_dte_chan", chan_ptr);
/* Invoke the channel process so that it can initialize itself. */
/* No arguments are needed for the initialization. */
op_pro_invoke (chan_ptr->process, OPC_NIL);
/* Invoke the channel process again so it can actually handle the call indication.*/
/* Include the call's first packet as an argument. */
op_pro_invoke (chan_ptr, pkptr);
Details
This KP invokes a process as a child of the currently executing process (the parent). Invocation of the child process occurs in the interrupt context of the parent and does not put a new event in the queue. A process can invoke any other process that is owned by the same module (that is, the module that is currently executing). A call to op_pro_invoke() with a process handle for a process that is owned by another module will result in a recoverable error.
There is no limit on the number of calls to op_pro_invoke() that can be made during a single event. In other words, a process that is interrupted as a result of a call to op_pro_invoke() can in turn invoke another process by means of the same KP. The series of processes invoked in this manner is referred to as the current invocation stack (similar to a function call stack). The Simulation Kernel limits processes from invoking other processes that are in the current invocation stack. This means that a process cannot invoke an active process, such as:
- the process that directly invoked it (its parent)
- the process that invoked its parent
- itself
Note that there is a distinction between a process instance and a process model. It is feasible, therefore, to invoke another process of the same type as the current process, but not the exact same process instance.
When an invocation takes place, the calling process has the ability to set up a block of memory that both itself and the called process share. This memory is referred to as argument memory because it is intended to pass parameters both into and out of the called process. The argument memory is available throughout the duration of the called process. The address of the memory block must be supplied as an argument to op_pro_invoke(). The called process can obtain this address by calling op_pro_argmem_access().
Purpose
Multiple processes can be designed to cooperate in handling events that occur within the context of a single queue or processor module. Frequently, these processes are organized in a hierarchical manner with parent processes "handing off" event-processing tasks to appropriate child processes, based on what the event requires. Other organizations are also possible with processes dividing tasks along functional lines. For example, different child processes can be invoked depending upon the type of interrupt received by the root process. Most organizational strategies have in common that they require the ability to temporarily pass execution control to child or peer processes within the module. This is accomplished by making a call to the KP op_pro_invoke() and supplying the process handle of the process that should execute.
Errors
- Program Abort: KP requires process context.
- 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>). - Recoverable Error: Process handle is for remote process (
<proc_id>). - Recoverable Error: Process handle is for active process (
<proc_id>).
Reference
- Use the KP op_pro_argmem_access() to obtain access to invocation argument memory
- Use the KP op_pro_parent() to obtain a process handle for a process' parent
- Use the KP op_pro_create() to create a new process and obtain a process handle for it