op_pro_destroy_options()
Abstract
Destroys a dynamically created process and (optionally) all outstanding events scheduled for that process.
Syntax
op_pro_destroy_options (pro_handle, options)
| Argument | Type | Description |
|---|---|---|
pro_handle |
Prohandle |
Process handle of the process that is to be destroyed |
options |
int |
Optional operations to be performed (see Details). |
Return Type
Compcode
Completion code indicating whether or not the Simulation Kernel successfully destroyed the process. This return code can be compared to the constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE to determine if the process destruction was successful.
Example
/* Destroy this process and clear process' outstanding events */
op_pro_destroy_options (op_pro_self(), OPC_PRO_DESTROY_OPT_NONE);
Details
This KP allows a process to destroy any other dynamic process that is owned by the same module (thus, the root process is the only process that cannot be destroyed in a given module). In addition, op_pro_destroy_options() optionally removes all outstanding events scheduled for the destroyed process. (A dynamic process is one created via the KP op_pro_create(); dynamic processes can be removed from the model at any time during the simulation.)
Proper termination of a process generally involves deallocation of dynamic memory that the process may have allocated, but may also include actions specific to the modeling application (such as reporting the value of a statistic accumulated during the process’ history). Process models have a special section of logic devoted to the processing that occurs when they are destroyed. This section is the process model’s Termination Block and the code contained within it is invoked directly by the Simulation Kernel when the process is destroyed. State and temporary variables may be used in this section of code.
A process may destroy itself, in which case it does not return. Therefore, no actions will be performed by a process after it destroys itself, with the exception of actions specified in the Termination Block.
Note: The Kernel assumes no responsibility for deallocation of parent-to-child or argument memory.
The options available for this KP are as follows:
OPC_PRO_DESTROY_OPT_KEEP_EVENTS— the KP does not remove any outstanding events scheduled for the process being destroyed (thus,op_pro_destroy_options()with this option works identically to op_pro_destroy()).OPC_PRO_DESTROY_OPT_NONE— default operation.
Purpose
Supports the removal and deallocation of dynamically created processes, with the optional removal of outstanding events scheduled for those processes. This provides the ability to keep active only those processes necessary to the correct operation of a processor or queue.
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 root process (
<proc_id>). - Recoverable Error: Process handle is for active process (
<proc_id>).
Reference
- Use the KP op_pro_create() to create new processes and obtain their handles
- Use the KP op_prg_mem_free() to deallocate memory allocated via op_prg_mem_alloc()
- Use the KP op_pro_invoke() to invoke a process
- Use the KP op_pro_parmem_access() to obtain the address of installed parent-to-child shared memory