op_ima_obj_event_notify()
Abstract
Enables link and transmitter-channel objects to be directly notified of certain events.
Syntax
op_ima_obj_event_notify (objid, event_type, start_service_time, end_service_time, num_bits, num_packets)
| Argument | Type | Description |
|---|---|---|
objid |
Objid |
object ID of the object-of-interest [An object ID can be obtained from several KPs in the Id and Topo packages: op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
event_type |
int |
numeric constant indicating the type of event that occurred [Currently the only legitimate value for this argument is OPC_IMA_PTTXCH_EVENT_PK_DEQUEUE.] |
start_service_time |
double |
time that the specified object begins processing this event. |
end_service_time |
double |
time that the specified object finishes processing this event. |
num_bits |
double |
number of bits processed by the object. |
num_packets |
double |
number of packets processed by the object. |
Return Type
Compcode
Completion code indicating whether the operation completed successfully.
This code can be compared to the two symbolic constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE.
Example
Excerpt from oms_bgutil.ex.c in models/std/utilities/oms.
/* Convert to total bits and total packets. */
num_bits = tx_drate * (full_util_end_time - full_util_start_time);
if (est_job_work_mean == 0.0)
{
num_pks = 0.0;
}
else
{
num_pks = (full_util_end_time — full_util_start_time) / est_job_work_mean;
}
/* Update the built-in link stats. */
op_ima_obj_event_notify (tx_ch_objid, OPC_IMA_PTTXCH_EVENT_PK_DEQUEUE,
full_util_start_time, full_util_end_time, num_bits, num_pks);
Details
This KP is currently limited to updating certain statistics in links and transmitter-channel objects. Only the following statistics (in the point-to-point group) can be updated using this KP: throughput (bits/sec), throughput (packets/sec), and utilization.
An object cannot process multiple calls of op_ima_obj_event_notify() at the same time. For this reason, each call to an object should have a unique service time as indicated by the start_service_time and end_service_time arguments. If consecutive calls with overlapping service times are made to the same object, the Simulation Kernel reschedules the subsequent event to a later time.
Purpose
In certain instances, a simulation run may contain events that are not included in the normal event-scheduling mechanism. As a result, some objects may need to be notified directly of an event by calling op_ima_obj_event_notify(). One situation where this can occur is when a model includes background routed traffic. Since the traffic is implicit, there are no corresponding events (such as the creation and transmission of packets) to trigger an update of a relevant statistic (such as a link object’s throughput). Currently, this KP’s primary purpose is for updating statistics in links and transmitter-channel objects that support background utilization traffic.
Errors
- Program Abort: Segmentation violation. (due to an invalid coordinate pointer)
- Recoverable Error: Object state not defined for object
<object_id>because it is of type (<object_type>). (This error occurs if the object is neither a link nor a transmitter channel object.) - Recoverable Error: Unknown event type (
<event_type_number>). (This error occurs if the event type is notOPC_IMA_PTTXCH_EVENT_PK_DEQUEUE.) - Recoverable Error: Object ID (
<site_objid>) refers to a restricted object.
Reference
- Use the KP op_pk_deliver() to deliver a packet to a remote module.
- Use the KP op_intrpt_schedule_remote() to interrupt a remote module.
- Use the KP op_ima_obj_pos_notification_register() to interrupt the current process when a site moves.
- Use the KP op_stat_reg()) to obtain a handle to reference a statistic.
- Use the KP op_stat_write() to write a value to a statistic wire connected to another module.
- Use the KP op_stat_write() to write a value to a statistic.
- Use the KP op_stat_write_t() to write a time-value pair of values to a statistic.