|Home > Iris APIs > Events and trace API > Creating and destroying event streams|
eventStream_create() creates a new event stream, which is identified by an event stream id,
esId. Event streams are destroyed by
eventStream_destroy() or by calling
instanceRegistry_unregisterInstance() either explicitly or implicitly.
eventStream_create() enables event generation for the selected
ec_< callback is
called on the instance specified by
ecInstId, which is usually the
client creating the event stream, with the requested event source fields, or a
superset of them.
There are internal checks and states associated with an event stream that might suppress event generation:
Enable flag. An event stream can be enabled or disabled. This state is controlled by:
eventStream_disable, see the
eventStream_destroy()do not take effect until the next sync point, in other words, the point at which a stop can be detected. Therefore, event generation might be delayed after calling
eventStream_create(), depending on the sync level of the event-producing instance and on the nature of the events, for example
INSTevents, which are generated by instruction execution. Stopping event generation might also be delayed after calling
eventStream_destroy(). For more information, see 5.19 Simulation accuracy (sync levels) API.
To stop generating events for a specific event stream that was
previously started with
client can call either:
eventStream_destroy(). The event stream id,
esId, is no longer valid after entering this function.
instanceRegistry_unregisterInstance(). This unregisters instance
Xand automatically destroys all event streams that were sent to instance
X, that is, event streams that were created using
Use the following guidelines on whether to use
eventStream_destroy()to enable and disable events interactively, at a low frequency. These functions might have some latency until events are generated, depending on the current sync level and the nature of the events. Only
eventStream_destroy()ensures all event generation overhead is removed. Use these functions if you can, or if you are unsure.
eventStream_disable()to enable and disable event generation at a high frequency, for example while the simulation is running. Trace points are an example of this. These functions usually have the lowest possible latency until event generation starts or stops. A disabled event stream might have a significant runtime overhead, depending on the frequency of the event. Use these functions only if you must.