Struct simics::api::base::event::Event

pub struct Event {
    name: String,
    cls: *mut ConfClass,
    flags: EventClassFlag,
    event_class: *mut EventClass,
}

Simplified event management mechanism using dynamic dispatch to circumvent complex trait requirements due to difference in callback specification and post time when using the canonical SIMICS APIs

Fields

name: String

The name of the event. This should identify the event uniquely.

cls: *mut ConfClass

The class the event will be posted for. This should be the class that is posting the events, not the class the events are posting on. For example, if you are implementing a module, cls should be the main class in your module.

flags: EventClassFlag

Flags of the event. Should either be 0 (the default), which indicates the event should not be saved, or [simics::api::sys::Sim_EC_Notsaved] which indicates this may not be saved in the configuration.

event_class: *mut EventClass

Implementations

impl Event

pub fn builder() -> EventBuilder<((), (), (), ())>

Create a builder for building Event. On the builder, call .name(...), .cls(...), .flags(...)(optional), .event_class(...)(optional) to set the values of the fields. Finally, call .build() to create the instance of Event.

impl Event

pub fn cls(&self) -> *mut ConfClass

Return the class an event is posted for

pub fn event_class(&self) -> *mut EventClass

Return the class of this event

pub fn register<S>( name: S, cls: *mut ConfClass, flags: EventClassFlag, ) -> Result<Self>

where S: AsRef<str>,

Register a new event to be posted for objects of class cl, and returns the event class to be used in other calls.

Arguments

• name - The name of the event to register for
• cls - The class events will be posted for objects of
• flags - Flags describing the events

Context

Global Context

pub fn post_time<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, seconds: f64, callback: F, ) -> Result<()>

where F: FnMut(*mut ConfObject) + 'static,

An event of evclass for object obj is posted on clock to occur at a given point in the future. The user_data will be associated with the event. The clock is the object that should be used for keeping track of time for the event. It can be a processor or an instance of the clock class.

If a configuration class was specified when evclass was registered, then obj must be an instance of that class.

The expiration point can be specified in seconds, cycles or steps by using the appropriate call, and these values are relative to the current state. Events that need to run synchronized (Sim_EC_Machine_Sync) can only be posted in seconds or cycles, not steps, since synchronization can only be perform in virtual time.

Note: Events posted with SIM_event_post_cycle are posted at a certain point in time based on the clock’s current frequency, not at a certain clock cycle. The difference is significant if the frequency of the clock object can change dynamically.

Arguments

• obj - The object the event is being posted on
• clock - The clock whose time this event is being posted for
• seconds - The number of seconds until this event expires
• callback - Callback to run for this event

Context

Cell Context

pub fn cancel_time( &self, obj: *mut ConfObject, clock: *mut ConfObject, ) -> Result<()>

All unexpired evclass events posted for obj on clock for which pred returns nonzero will be cancelled and their destructor methods (if any) called. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), all evclass events for obj on clock will be cancelled.

There are separate calls for events posted at a point in time (cycle or seconds) and on a specific step.

Arguments

• obj - The object the event was posted on
• clock - The clock the event to cancel was posted on

Context

Cell Context

pub fn cancel_time_filter<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, filter: Option<F>, ) -> Result<()>

where F: Fn(*mut c_void) -> i32 + 'static,

👎Deprecated: Filter function will not be freed. This will lead to memory leaks.

All unexpired evclass events posted for obj on clock for which pred returns nonzero will be cancelled and their destructor methods (if any) called. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), all evclass events for obj on clock will be cancelled.

There are separate calls for events posted at a point in time (cycle or seconds) and on a specific step.

Arguments

• obj - The object the event was posted on
• clock - The clock the event to cancel was posted on
• filter - The filter function. Note that there is a limitation currently which does not allow this filter function to be freed once it is boxed, which can lead to memory leaks, so this method is deprecated as a warning.

Context

Cell Context

pub fn post_step<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, steps: PcStep, callback: F, ) -> Result<()>

where F: FnMut(*mut ConfObject) + 'static,

An event of evclass for object obj is posted on clock to occur at a given point in the future. The user_data will be associated with the event. The clock is the object that should be used for keeping track of time for the event. It can be a processor or an instance of the clock class.

If a configuration class was specified when evclass was registered, then obj must be an instance of that class.

The expiration point can be specified in seconds, cycles or steps by using the appropriate call, and these values are relative to the current state. Events that need to run synchronized (Sim_EC_Machine_Sync) can only be posted in seconds or cycles, not steps, since synchronization can only be perform in virtual time.

Note: Events posted with SIM_event_post_cycle are posted at a certain point in time based on the clock’s current frequency, not at a certain clock cycle. The difference is significant if the frequency of the clock object can change dynamically.

Arguments

• obj - The object the event is being posted on
• clock - The clock whose time this event is being posted for
• steps - The number of seconds until this event expires
• callback - Callback to run for this event

Context

Cell Context

pub fn cancel_step( &self, obj: *mut ConfObject, clock: *mut ConfObject, ) -> Result<()>

All unexpired evclass events posted for obj on clock for which pred returns nonzero will be cancelled and their destructor methods (if any) called. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), all evclass events for obj on clock will be cancelled.

There are separate calls for events posted at a point in time (cycle or seconds) and on a specific step.

Arguments

• obj - The object the event was posted on
• clock - The clock the event to cancel was posted on

Context

Cell Context

pub fn cancel_step_filter<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, filter: Option<F>, ) -> Result<()>

where F: Fn(*mut c_void) -> i32 + 'static,

👎Deprecated: Filter function will not be freed. This will lead to memory leaks.

All unexpired evclass events posted for obj on clock for which pred returns nonzero will be cancelled and their destructor methods (if any) called. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), all evclass events for obj on clock will be cancelled.

There are separate calls for events posted at a point in time (cycle or seconds) and on a specific step.

Arguments

• obj - The object the event was posted on
• clock - The clock the event to cancel was posted on
• filter - The filter function. Note that there is a limitation currently which does not allow this filter function to be freed once it is boxed, which can lead to memory leaks, so this method is deprecated as a warning.

Context

Cell Context

pub fn post_cycle<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, cycles: Cycles, callback: F, ) -> Result<()>

where F: FnMut(*mut ConfObject) + 'static,

An event of evclass for object obj is posted on clock to occur at a given point in the future. The user_data will be associated with the event. The clock is the object that should be used for keeping track of time for the event. It can be a processor or an instance of the clock class.

If a configuration class was specified when evclass was registered, then obj must be an instance of that class.

The expiration point can be specified in seconds, cycles or steps by using the appropriate call, and these values are relative to the current state. Events that need to run synchronized (Sim_EC_Machine_Sync) can only be posted in seconds or cycles, not steps, since synchronization can only be perform in virtual time.

Note: Events posted with SIM_event_post_cycle are posted at a certain point in time based on the clock’s current frequency, not at a certain clock cycle. The difference is significant if the frequency of the clock object can change dynamically.

Arguments

• obj - The object the event is being posted on
• clock - The clock whose time this event is being posted for
• cycles - The number of seconds until this event expires
• callback - Callback to run for this event

Context

Cell Context

pub fn find_next_time( &self, obj: *mut ConfObject, clock: *mut ConfObject, ) -> Result<f64>

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

pub fn find_next_time_filter<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, filter: F, ) -> Result<f64>

where F: Fn(*mut c_void) -> i32 + 'static,

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on
• filter - A function to filter objects by returning true or false

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

pub fn find_next_cycle( &self, obj: *mut ConfObject, clock: *mut ConfObject, ) -> Result<Cycles>

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

pub fn find_next_cycle_filter<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, filter: F, ) -> Result<Cycles>

where F: Fn(*mut c_void) -> i32 + 'static,

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on
• filter - A function to filter objects by returning true or false

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

pub fn find_next_step( &self, obj: *mut ConfObject, clock: *mut ConfObject, ) -> Result<PcStep>

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

pub fn find_next_step_filter<F>( &self, obj: *mut ConfObject, clock: *mut ConfObject, filter: F, ) -> Result<PcStep>

where F: Fn(*mut c_void) -> i32 + 'static,

Return the number of cycles/seconds/steps to the first event of evclass of obj posted on clock for which pred is true, or −1 if no event matched. pred will be called with the data associated with the event and the supplied match_data. If pred is null (None in Python), the first evclass event for obj on clock will be used.

There are separate calls of events posted at a point in time (cycle or seconds) and on a specific step. Note that the return value of SIM_event_find_next_cycle is only a preliminary estimate; the number of remaining cycles will change if the clock’s frequency changes dynamically. To handle dynamically changing clock frequencies correctly, subscribe to the frequency changes via the clock’s simple_dispatcher interface.

Arguments

• clock - The clock for the posted event
• obj - The object posted on
• filter - A function to filter objects by returning true or false

Return Value

If found, the cycle number the event will next trigger on

Context

Cell Context

Trait Implementations

impl Clone for Event

fn clone(&self) -> Event

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Event

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.