 |
EM-ODP
3.8.0-1
Event Machine on ODP
|
|
EM-ODP
3.8.0-1
Event Machine on ODP
|
Data Structures | |
| struct | em_fract_u64_t |
| struct | em_timer_res_param_t |
| struct | em_timer_ring_param_t |
| struct | em_timer_attr_t |
| struct | em_tmo_stats_t |
| struct | em_timer_capability_t |
| struct | em_tmo_args_t |
Typedefs | |
| typedef enum em_tmo_state_t | em_tmo_state_t |
| typedef enum em_tmo_type_t | em_tmo_type_t |
| typedef uint64_t | em_timer_tick_t |
| typedef struct em_fract_u64_t | em_fract_u64_t |
| typedef struct em_timer_res_param_t | em_timer_res_param_t |
| typedef struct em_timer_ring_param_t | em_timer_ring_param_t |
| typedef struct em_timer_attr_t | em_timer_attr_t |
| typedef struct em_tmo_stats_t | em_tmo_stats_t |
| typedef struct em_timer_capability_t | em_timer_capability_t |
| typedef struct em_tmo_args_t | em_tmo_args_t |
| typedef struct em_timer_timeout_t * | em_tmo_t |
Enumerations | |
| enum | em_tmo_state_t { EM_TMO_STATE_UNKNOWN = 0 , EM_TMO_STATE_IDLE = 1 , EM_TMO_STATE_ACTIVE = 2 , EM_TMO_STATE_INACTIVE = 3 } |
| enum | em_tmo_type_t { EM_TMO_TYPE_NONE = 0 , EM_TMO_TYPE_ONESHOT = 1 , EM_TMO_TYPE_PERIODIC = 2 } |
| enum | em_timer_flag_t { EM_TIMER_FLAG_NONE = 0 , EM_TIMER_FLAG_PRIVATE = 1 , EM_TIMER_FLAG_RING = 2 } |
| enum | em_tmo_flag_t { EM_TMO_FLAG_ONESHOT = 1 , EM_TMO_FLAG_PERIODIC = 2 , EM_TMO_FLAG_NOSKIP = 4 } |
| enum | em_timer_clksrc_t { EM_TIMER_CLKSRC_0 , EM_TIMER_CLKSRC_1 , EM_TIMER_CLKSRC_2 , EM_TIMER_CLKSRC_3 , EM_TIMER_CLKSRC_4 , EM_TIMER_CLKSRC_5 , EM_TIMER_NUM_CLKSRC } |
Event Machine timer
Event Machine timer
The timer API can be used to request an event to be sent to a specified queue at a specified time once (one-shot) or at regular intervals (periodic). A timer needs to be created first - it represents a collection of timeouts with certain attributes (e.g. timeout resolution and maximum period). A timer can be mapped to a HW resource on an SoC, thus the number of timers, capabilities and time bases are system specific. Typically only a few timers are supported. The application can specify required capabilities when a timer is created. The creation will fail if the implementation cannot fulfill the required values. Timers are typically created once at system startup.
A timer is a shared resource with proper synchronization for concurrent multi-thread use. It is possible to exclude all multi-thread protections if a timer is used exclusively by a single thread (for potential performance gains). This is done by setting EM_TIMER_FLAG_PRIVATE when creating a timer. Setting this flag means that the application must ensure that only a single thread is using the timer (this also includes the receiver of periodic timeouts due to the ack-functionality). This private-mode is not necessarily implemented on all systems, in which case the flag is ignored as it will not cause any functional difference.
Timeouts (tmo) can be created once a timer exists. Creating a timeout allocates the resources needed to serve the timeout, but does not arm it. This makes it possible to pre-create timeout(s) and set the expiry later at runtime. This can improve performance but also minimizes the possibility that the runtime call setting the expiry would fail, as resources have already been reserved beforehand.
A pending timeout can be cancelled. Note that there is no way to cancel an expired timeout for which the event has already been sent but not yet received by the application. Canceling in this case will return an error to enable the application to detect the situation. For a periodic timer, a cancel will stop further timeouts, but may not be able to prevent the latest event from being received. An active timeout cannot be altered without canceling it first.
A timeout can be reused after the timeout event has been received or when successfully cancelled. Timeouts need to be deleted after use. Deletion frees the resources reserved during creation.
The timeout value is an abstract system and timer dependent tick count. It is assumed that the tick count increases with a static frequency. The frequency can be inquired at runtime for time calculations, e.g. tick frequency divided by 1000 gives ticks for 1ms. The tick frequency is at least equal to the resolution, but can also be higher (implementation can quantize ticks to any underlying implementation). The supported resolution can also be inquired. A clock source can be specified when creating a timer. It defines the time base of the timer for systems with multiple sources implemented (optional). EM_TIMER_CLKSRC_DEFAULT is a portable value that implements a basic monotonic time, that will not wrap back to zero in any reasonable uptime.
Events with major event types EM_EVENT_TYPE_SW, EM_EVENT_TYPE_PACKET and EM_EVENT_TYPE_TIMER can be used as timeout events to indicate expiry. The type EM_EVENT_TYPE_TIMER is an alternative to EM_EVENT_TYPE_SW and works the same way. Additionally, for periodic ring timer only, the type EM_EVENT_TYPE_TIMER_IND is used. This is a special timeout indication event without visible payload.
Regular periodic timeouts: (i.e. NOT periodic ring timer timeouts, see differences further down) A periodic timer requires the application to acknowledge each received timeout event after it has been processed. The acknowledgment activates the next timeout and compensates for the processing delay to keep the original interval. This creates a flow control mechanism and also protects the event handling from races if the same event is reused every time - the next timeout will not be sent before the previous has been acknowledged. The event to be received for each periodic timeout can also be different as the next event is given by the application via the acknowledgment. The target queue cannot be modified after the timeout has been created.
If the acknowledgment of a periodic timeout is done too late (after the next period has already passed), the default action is to skip the missed timeout slot(s) and arm for the next valid slot. If the application never wants to skip a missed timeout it can set the flag EM_TMO_FLAG_NOSKIP when creating a timeout. This causes each acknowledgment to schedule an immediate timeout event until all the missed time slots have been served. This keeps the number of timeouts as expected but may cause an event storm if a long processing delay has occurred.
The timeout handle is needed when acknowledging a periodic timeout event. Because any event can be used for the timeout, the application must itself provide a way to derive the timeout handle from the received timeout event. A typical way is to include the tmo handle within the timeout event. The application also needs to have a mechanism to detect which event is a periodic timeout to be able to acknowledge it via em_tmo_ack().
If the requested timeout tick value for a timeout is in the past or is too close to the current time then the error code EM_ERR_TOONEAR is returned. In this case EM will not call the error handler - instead EM lets the application decide whether to treat the situation as an error or to try again with an updated target time.
Periodic ring timer: There is also an alternative periodic ring timer. It uses a different abstraction and is created and started via separate ring specific APIs. It has three main differences to the regular periodic timeouts:
Ring timers can be thought of as a clock face ticking the pointer forward. One cycle around is the base rate (minimum rate). The same timeout can be inserted into multiple locations evenly spread within the clock face thus multiplying the base rate. The starting offset can be adjusted only up to one timeout period. Depending on platform, this mode may provide better integration with HW and thus have less runtime overhead. However, as it exposes a potential queue overflow and a race hazard (race avoidable by using atomic queue as target), regular periodic timeouts are recommended as a default.
Example usage
| typedef struct em_fract_u64_t em_fract_u64_t |
Fractional 64-bit unsigned value for timer frequency.
| typedef struct em_timer_attr_t em_timer_attr_t |
EM timer attributes.
The type is used when creating a timer or inquiring its configuration later.
This needs to be initialized with em_timer_attr_init(), which fills default values to each field. After that the values can be modified as needed. Values set are considered a requirement, e.g. setting 'resparam.res_ns' to 1000(ns) requires the timer to have at least 1us resolution. The timer creation will fail if the implementation cannot support such a resolution (e.g. if it only goes down to 1500ns). The implementation is free to provide better than requested, but not worse.
To know the implementation specific limits, use em_timer_capability() and em_timer_res_capability().
When creating the alternative periodic ring timer, this type needs to be initialized with em_timer_ring_attr_init() instead. EM_TIMER_FLAG_RING will be set by em_timer_ring_attr_init() so it does not need to be manually set.
| typedef struct em_timer_capability_t em_timer_capability_t |
Timer capability info
| typedef struct em_timer_res_param_t em_timer_res_param_t |
Type for timer resolution parameters.
This structure is used to group timer resolution parameters that may affect each other. All time values are in nanoseconds (ns).
| typedef struct em_timer_ring_param_t em_timer_ring_param_t |
Periodic timer ring timing parameters.
| typedef uint64_t em_timer_tick_t |
The timer tick has HW and timer specific meaning, but the type is always a 64-bit integer and is normally assumed to be monotonic and not to wrap around. Exceptions with exotic extra timers should be clearly documented.
Definition at line 255 of file api/event_machine_timer.h.
| typedef struct em_tmo_args_t em_tmo_args_t |
tmo optional extra arguments
| typedef enum em_tmo_state_t em_tmo_state_t |
Visible state of a timeout
| typedef struct em_tmo_stats_t em_tmo_stats_t |
Timeout statistics counters
Some fields relate to periodic timeout only (0 on one-shots) and vice versa. New fields may be added later at the end.
em_tmo_t (timeout handle) needs to be defined by the EM implementation
System specific type for a timeout handle.
Definition at line 70 of file event_machine_timer_hw_specific.h.
| typedef enum em_tmo_type_t em_tmo_type_t |
Type returned by em_tmo_get_type()
| enum em_timer_clksrc_t |
System specific enum type for timer clock source. This is system specific, but all implementations must define EM_TIMER_CLKSRC_DEFAULT.
Definition at line 95 of file event_machine_timer_hw_specific.h.
| enum em_timer_flag_t |
System specific type for timer flags. This is system specific, but all implementations must define EM_TIMER_FLAG_DEFAULT and EM_TIMER_FLAG_PRIVATE, of which the latter is used to skip API synchronization for single threaded apps. Flags can be combined by bitwise OR.
Definition at line 57 of file event_machine_timer_hw_specific.h.
| enum em_tmo_flag_t |
System specific enum type for timeout flags. This is system specific, but all implementations must define EM_TMO_FLAG_ONESHOT, EM_TMO_FLAG_PERIODIC and EM_TMO_FLAG_NOSKIP. Flags can be combined by bitwise OR.
| Enumerator | |
|---|---|
| EM_TMO_FLAG_ONESHOT | to select one-shot |
| EM_TMO_FLAG_PERIODIC | to select periodic |
| EM_TMO_FLAG_NOSKIP | see periodic ack |
Definition at line 80 of file event_machine_timer_hw_specific.h.
| enum em_tmo_state_t |
Visible state of a timeout
| Enumerator | |
|---|---|
| EM_TMO_STATE_IDLE | just created or canceled |
| EM_TMO_STATE_ACTIVE | armed |
| EM_TMO_STATE_INACTIVE | unused state |
Definition at line 234 of file api/event_machine_timer.h.
| enum em_tmo_type_t |
Type returned by em_tmo_get_type()
| Enumerator | |
|---|---|
| EM_TMO_TYPE_NONE | unknown or not a timer-related event |
| EM_TMO_TYPE_ONESHOT | event is a oneshot timeout indication |
| EM_TMO_TYPE_PERIODIC | event is a periodic timeout indication |
Definition at line 244 of file api/event_machine_timer.h.
| void em_timer_attr_init | ( | em_timer_attr_t * | tmr_attr | ) |
Initialize em_timer_attr_t for normal timers (i.e. NOT periodic ring timers).
Initializes em_timer_attr_t to system specific default values. The user can after initialization adjust the values as needed before calling em_timer_create(). The functions em_timer_capability() and/or em_timer_res_capability() can optionally be used to find valid values.
Always initialize em_timer_attr_t with em_timer_attr_init() before use.
This function will not trigger EM error handler calls internally.
Example for all defaults
| tmr_attr | Pointer to em_timer_attr_t to be initialized |
Definition at line 378 of file event_machine_timer.c.
| em_status_t em_timer_capability | ( | em_timer_capability_t * | capa, |
| em_timer_clksrc_t | clk_src | ||
| ) |
Inquire timer capabilities
Returns timer capabilities for the given clock source, which is also written to both 'capa->max_res.clk_src' and 'capa->max_tmo.clk_src'. For resolution both 'res_ns' and 'res_hz' are filled.
This function will not trigger error handler calls internally.
| capa | pointer to em_timer_capability_t to be updated (does not need to be initialized) |
| clk_src | Clock source to use for timer (EM_TIMER_CLKSRC_DEFAULT for system specific default) |
Definition at line 502 of file event_machine_timer.c.
| em_timer_t em_timer_create | ( | const em_timer_attr_t * | tmr_attr | ) |
Create and start a timer resource
Required attributes are given via tmr_attr. The given structure must be initialized with em_timer_attr_init() before setting any field.
Timer resolution can be given as time 'res_ns' or frequency 'res_hz'. The user must choose which one to use by setting the other one to 0.
To use all defaults, initialize tmr_attr with em_timer_attr_init() and pass it as is to em_timer_create().
| tmr_attr | Timer parameters to use, pointer to an initialized em_timer_attr_t |
Definition at line 616 of file event_machine_timer.c.
| em_timer_tick_t em_timer_current_tick | ( | em_timer_t | tmr | ) |
Return the current tick value of the given timer
This can be used for calculating absolute timeouts.
| tmr | Timer handle |
Definition at line 1045 of file event_machine_timer.c.
| em_status_t em_timer_delete | ( | em_timer_t | tmr | ) |
Stop and delete a timer
Delete a timer, free all resources. All timeouts for this timer must have been cancelled and deleted first.
| tmr | Timer handle |
Definition at line 980 of file event_machine_timer.c.
| int em_timer_get_all | ( | em_timer_t * | tmr_list, |
| int | max | ||
| ) |
Get a list of currently active timers.
The timer handles returned via 'tmr_list' can be used for further timer queries or to destroy existing timers.
The return value always reflects the actual number of timers in the EM instance but the output parameter 'tmr_list' is only written up to the given 'max' length.
Note that the return value (number of timers) can be greater than the given 'max'. It is the user's responsibility to check the return value against the given 'max'.
To only get the current number of active timers, without any timer handles output, use the following: num_timers = em_timer_get_all(NULL, 0);
| [out] | tmr_list | Pointer to an array of timer handles. Use NULL if only interested in the return value. |
| max | Max number of handles that can be written into 'tmr_list'. 'max' is ignored if 'tmr_list' is NULL. |
Definition at line 1728 of file event_machine_timer.c.
| em_status_t em_timer_get_attr | ( | em_timer_t | tmr, |
| em_timer_attr_t * | tmr_attr | ||
| ) |
Get timer attributes
Returns the actual capabilities of the given timer.
| tmr | Timer handle | |
| [out] | tmr_attr | Pointer to em_timer_attr_t to fill |
Definition at line 1752 of file event_machine_timer.c.
| uint64_t em_timer_get_freq | ( | em_timer_t | tmr | ) |
Returns the timer frequency, i.e. ticks per second, for the given timer.
Can be used to convert real time to timer specific ticks.
| tmr | Timer handle |
Definition at line 1797 of file event_machine_timer.c.
| em_timer_tick_t em_timer_ns_to_tick | ( | em_timer_t | tmr, |
| uint64_t | ns | ||
| ) |
Convert nanoseconds (ns) to timer ticks
| tmr | Valid timer handle |
| ns | ns value to convert |
Definition at line 1824 of file event_machine_timer.c.
| em_status_t em_timer_res_capability | ( | em_timer_res_param_t * | res, |
| em_timer_clksrc_t | clk_src | ||
| ) |
Inquire timer capabilities for a specific resolution or maximum timeout
Returns timer capabilities by the given resolution or maximum timeout. Set either the resolution (res.res_ns) or the maximum timeout (res.max_tmo) to the required value and the other to zero, and the function will fill the other fields with valid limits. An error is returned if the given value is not supported. The given clk_src is used to set the values and also written to 'res->clk_src'. Both 'res_ns' and 'res_hz' are filled, so if passed further to em_timer_create(), one of those must be set to 0.
Example for external clock maximum resolution
This function will not trigger error handler calls internally.
| res | Pointer to em_timer_res_param_t with one field set |
| clk_src | Clock source to use for timer (EM_TIMER_CLKSRC_DEFAULT for system specific default) |
Definition at line 544 of file event_machine_timer.c.
| em_status_t em_timer_ring_attr_init | ( | em_timer_attr_t * | ring_attr, |
| em_timer_clksrc_t | clk_src, | ||
| uint64_t | base_hz, | ||
| uint64_t | max_mul, | ||
| uint64_t | res_ns | ||
| ) |
Initialize em_timer_attr_t for periodic ring timers.
Initializes em_timer_ring_attr_t according to given values. After successful return, the attributes can be given to em_timer_ring_create(). Note, that if the implementation cannot use the exact given combination it may update the ring_attr values, but always to meet or exceed the given values. The user can read the new values to determine if they were modified. An error is returned if the given values cannot be met.
Before creating the ring timer, other values like num_tmo and name can be adjusted as needed. Also, if a non-integer frequency is needed, the base_hz fractional part can be adjusted before em_timer_ring_create().
This function will not trigger error handler calls.
| [out] | ring_attr | Pointer to em_timer_attr_t to be initialized |
| clk_src | Clock source to use (system specific or portable EM_TIMER_CLKSRC_DEFAULT) | |
| base_hz | Base rate of the ring (minimum rate i.e. longest period) | |
| max_mul | Maximum multiplier (maximum rate = base_hz * max_mul) | |
| res_ns | Required resolution of the timer or 0 to accept default |
Definition at line 444 of file event_machine_timer.c.
| em_status_t em_timer_ring_capability | ( | em_timer_ring_param_t * | ring | ) |
Check periodic ring timer capability.
Returns the ring timer capability based on the given input values. The parameter 'ring' must be initialized with the values required by the user. The ring.res_ns can be 0 and gets replaced by the system default. The values are updated during the call. If EM_OK is returned then the combination of given values are all supported (or exceeded, e.g. better resolution), otherwise values are updated with the closest supported.
As em_timer_ring_attr_init() only takes integer base_hz, this can also be used to verify valid values for modified fractional frequencies to avoid error handler calls from em_timer_ring_create().
This function will not trigger error handler calls.
| ring[in,out] | timer ring parameters to check |
| EM_OK | Parameter combination is supported |
| EM_ERR_NOT_SUPPORTED | Parameters not supported, values updated to closest |
| (other | error) Unsupported arguments |
Definition at line 577 of file event_machine_timer.c.
| em_timer_t em_timer_ring_create | ( | const em_timer_attr_t * | ring_attr | ) |
Create and start a periodic timer ring (alternative periodic timer)
The required attributes are given via ring_attr, which must have been initialized with em_timer_ring_attr_init() and optionally adjusted for the required timing constraints.
A periodic ring timer is a bit different and will only send EM_EVENT_TYPE_TIMER_IND timeout events, which are automatically provided and cannot be modified. These events can be allocated only via timer APIs.
Example for 1ms ... 125us periodic ring timer (base 1000 hz, multiplier up to 8):
| ring_attr | Timer ring parameters to use |
Definition at line 770 of file event_machine_timer.c.
| uint64_t em_timer_tick_to_ns | ( | em_timer_t | tmr, |
| em_timer_tick_t | ticks | ||
| ) |
Convert timer ticks to nanoseconds (ns)
| tmr | Valid timer handle |
| ticks | Timer specific ticks to convert |
Definition at line 1811 of file event_machine_timer.c.
| uint64_t em_timer_to_u64 | ( | em_timer_t | timer | ) |
Convert a timer handle to an unsigned integer.
| timer | Timer handle to be converted. |
Definition at line 1942 of file event_machine_timer.c.
| em_status_t em_tmo_ack | ( | em_tmo_t | tmo, |
| em_event_t | next_tmo_ev | ||
| ) |
Acknowledge a periodic timeout
All received periodic timeout events must be acknowledged with em_tmo_ack(). No further timeout event(s) will be sent before the user has acknowledged the previous one unless a ring timer is used.
Timeout acknowledgment is usually done at the end of the EO-receive function to prevent race conditions (e.g. if the same event is reused for the next timeout period also). The implementation will adjust for the processing delay so that the time slot will not drift over time.
If em_tmo_ack() is called too late, e.g. the next period(s) is already passed, the implementation by default will skip all the missed time slots and arm for the next future one keeping the original start offset. The application can alter this behaviour with the flag 'EM_TMO_FLAG_NOSKIP' when creating a timeout: no past timeout will be skipped and each late acknowledgment will immediately trigger sending the next timeout event until the current time has been reached. Note that using 'EM_TMO_FLAG_NOSKIP' may result in an event storm if a large number of timeouts have been unacknowledged for a longer time (limited by application response latency). Timing problems will not call the EM error handler.
If the timeout has been canceled, but the cancel happened too late for the current period, the timeout event will still be delivered. The em_tmo_ack() call for this event will return 'EM_ERR_CANCELED' and does not call the error handler. This error code signals that the timeout event was the last one coming for that, now cancelled, timeout.
The application may reuse the same received timeout event or provide a new one for the next timeout via 'next_tmo_ev'. With a periodic ring timer, the actual received event must be always be passed via 'next_tmo_ev'.
The given event should not be touched after calling this function until it has been received again or after the timeout is successfully cancelled and event returned.
A regular periodic timeout (i.e. not a ring one) will stop if em_tmo_ack() returns an error other than related to timing. Unless the timeout was canceled, the implementation will call the EM error handler in this case (the error/exception can be handled also there).
em_tmo_ack() can only be used with periodic timeouts.
| tmo | Timeout handle |
| next_tmo_ev | Next timeout event handle. Can be the received one for regular periodic timeouts. Must be the received one for periodic ring timeouts. |
| EM_OK | Success, event taken. |
| EM_ERR_CANCELED | Timer cancelled, last event - no further timeout events coming, event not taken. |
| (other_codes) | Failure, event not taken. |
Definition at line 1612 of file event_machine_timer.c.
| em_status_t em_tmo_cancel | ( | em_tmo_t | tmo, |
| em_event_t * | cur_event | ||
| ) |
Cancel a timeout
Cancels a timeout preventing future expiration. Returns the timeout event if the timeout has not expired. A timeout that has already expired, or just is about to, is too late to be cancelled and the timeout event will be delivered to the destination queue. In this case the error 'EM_ERR_TOONEAR' is returned - no EM error handler is called.
Periodic timeout: cancel may fail if attempted too close to the next period. This can be considered normal and indicates that at least one more timeout event will be delivered to the user. In this case, the error 'EM_ERR_TOONEAR' is returned and no valid event is output. The EM error handler is not called is this scenario. The user calls em_tmo_ack() for each received periodic timeout event. The em_tmo_ack() function returns 'EM_ERR_CANCELED' for the last timeout event from the cancelled periodic timeout to let the user know that it is now OK to e.g. delete the timeout.
| tmo | Timeout handle | |
| [out] | cur_event | Event handle pointer to return the pending timeout event for a successful cancel or EM_EVENT_UNDEF if cancel fails (e.g. called too late) |
| EM_OK | Cancel successful, timeout event returned. |
| EM_ERR_TOONEAR | Timeout already expired, too late to cancel. EM error handler is not called. |
| (other_codes) | Failure |
Definition at line 1533 of file event_machine_timer.c.
| em_tmo_t em_tmo_create | ( | em_timer_t | tmr, |
| em_tmo_flag_t | flags, | ||
| em_queue_t | queue | ||
| ) |
Allocate a new timeout
Create a new timeout. Allocates the necessary internal resources from the given timer and prepares for em_tmo_set_abs/rel/periodic().
Scheduled queues are always supported as timeout event destinations. LOCAL or OUTPUT queues can not be used as timeout targets. Support for unscheduled queues is implementation specific.
Flags are used to select functionality:
The NOSKIP flag is ignored if used timer is a periodic timer ring.
| tmr | Timer handle |
| flags | Functionality flags |
| queue | Target queue where the timeout event should be delivered |
Definition at line 1056 of file event_machine_timer.c.
| em_tmo_t em_tmo_create_arg | ( | em_timer_t | tmr, |
| em_tmo_flag_t | flags, | ||
| em_queue_t | queue, | ||
| em_tmo_args_t * | args | ||
| ) |
Allocate a new timeout with extra arguments
Similar to em_tmo_create() but with an additional 'args' pointer. This API can be used with any timer type, but 'args->userptr' is only meaningful for ring timers using events of type EM_EVENT_TYPE_TIMER_IND that can carry a 'userptr'.
| tmr | Timer handle |
| flags | Functionality flags |
| queue | Target queue where the timeout event should be delivered |
| args | Optional pointer holding extra arguments e.g. userptr for ring timers. NULL ok. |
Definition at line 1061 of file event_machine_timer.c.
| em_status_t em_tmo_delete | ( | em_tmo_t | tmo | ) |
Delete a timeout
The deleted timeout must be inactive i.e. it must be successfully canceled or the last timeout event must have been received (following too late a cancel). A periodic or a periodic ring timeout can be deleted after a successful cancel or after em_tmo_ack() returned EM_ERR_CANCELED. This indicates that the acknowledged timeout is canceled and that it was the last timeout event coming for that periodic timeout.
After and during this call, the tmo handle is not valid anymore and must not be used by or passed to other timer APIs.
| tmo | Timeout handle |
Definition at line 1161 of file event_machine_timer.c.
| em_tmo_state_t em_tmo_get_state | ( | em_tmo_t | tmo | ) |
Returns the current state of the given timeout.
Note that the returned state may change at any time if the timeout expires or is manipulated by other threads.
| tmo | Timeout handle |
Definition at line 1837 of file event_machine_timer.c.
| em_status_t em_tmo_get_stats | ( | em_tmo_t | tmo, |
| em_tmo_stats_t * | stat | ||
| ) |
Returns the statistic counters for a timeout.
Returns a snapshot of the current counters of the given timeout. Statistics can be accessed while the timeout is valid, i.e. tmo created but not deleted.
Counter support is optional. If counters are not supported, the function returns 'EM_ERR_NOT_IMPLEMENTED'. A quick way to detect whether counters are supported is to call the function with 'stat=NULL' and check the return value.
| tmo | Timeout handle | |
| [out] | stat | Pointer to em_tmo_stats_t to receive the values (NULL ok) |
Definition at line 1851 of file event_machine_timer.c.
| em_timer_t em_tmo_get_timer | ( | em_tmo_t | tmo | ) |
Returns the associated timer handle from a timeout handle
The associated timer handle is returned from a valid timeout. Can be used to e.g. read the current timer tick without having the timer handle:
| tmo | Valid timeout handle |
Definition at line 1928 of file event_machine_timer.c.
| em_tmo_type_t em_tmo_get_type | ( | em_event_t | event, |
| em_tmo_t * | tmo, | ||
| bool | reset | ||
| ) |
Ask if the given event is currently used as a timeout indication event.
This function can be used with any valid event handle to ask if it is used as a timeout indication event. Events are updated to a tmo-type when going through the timer API.
A successful timeout cancel (event returned) will reset the event type to 'EM_TMO_TYPE_NONE'.
The related tmo handle can be retrieved via the 'tmo' argument. This can be useful when calling em_tmo_ack() for periodic timeouts:
| event | Event handle to check. | |
| [out] | tmo | em_tmo_t pointer to output the related tmo handle. Use NULL if not interested in the tmo handle. |
| reset | Set to 'true' to reset the event's tmo type to 'EM_TMO_TYPE_NONE' to e.g. enable non-timer related reuse of the event. |
Definition at line 1874 of file event_machine_timer.c.
| void* em_tmo_get_userptr | ( | em_event_t | event, |
| em_tmo_t * | tmo | ||
| ) |
Returns the optional user pointer for a periodic ring timeout.
Can only be used with an event received as a timeout event for a periodic ring, i.e. for events of type 'EM_EVENT_TYPE_TIMER_IND' only. Other event types will return NULL.
| event | Event received as timeout | |
| [out] | tmo | Optionally returns associated tmo handle. NULL ok. |
Definition at line 1907 of file event_machine_timer.c.
| em_status_t em_tmo_set_abs | ( | em_tmo_t | tmo, |
| em_timer_tick_t | ticks_abs, | ||
| em_event_t | tmo_ev | ||
| ) |
Activate a oneshot timeout with absolute time.
Activates a oneshot timeout to expire at a specific absolute time. The given timeout event will be sent to the queue given to em_tmo_create() when the timeout expires.
It is not possible to send timeouts with an event group, but the application can assign the event group when receiving the timeout event, see em_event_group_assign().
The timeout event should not be accessed after it has been given to the timer, similar to sending an event.
Even if not guaranteed, the implementation should make sure that this call can fail only in exceptional situations (em_tmo_create() should pre-allocate needed resources).
The allowed minimum and maximum timeouts can be inquired with em_timer_res_capability().
An active timeout can not be modified. The timeout needs to be canceled and then set again with new arguments.
An inactive timeout can be reused by calling em_tmo_set_abs/rel() again. The timeout becomes inactive after the oneshot timeout event has been received or after it has been successfully cancelled.
This function is for activating oneshot timeouts only. To activate periodic timeouts use em_tmo_set_periodic() (or em_tmo_set_periodic_ring()).
| tmo | Timeout handle |
| ticks_abs | Expiration time in absolute timer specific ticks |
| tmo_ev | Timeout event |
| EM_OK | Success, event taken. |
| EM_ERR_TOONEAR | Failure, the tick value is in past or too close to the current time. Error handler not called, event not taken. |
| (other_codes) | Failure, event not taken. |
Definition at line 1225 of file event_machine_timer.c.
| em_status_t em_tmo_set_periodic | ( | em_tmo_t | tmo, |
| em_timer_tick_t | start_abs, | ||
| em_timer_tick_t | period, | ||
| em_event_t | tmo_ev | ||
| ) |
Activate a periodic timeout
Used to activate periodic timeouts. The first period can be different from the repetitive period by providing an absolute start time. Set 'start_abs' to 0 if the repetitive period can start from the moment of the call.
The timeout event will be sent to the queue given to em_tmo_create() when the first timeout expires. The receiver then needs to call em_tmo_ack() to allow the timer to send the next event for the following period.
This function can only be used with periodic timeouts (created with flag EM_TMO_FLAG_PERIODIC).
| tmo | Timeout handle |
| start_abs | Absolute start time (or 0 for period starting at call time) |
| period | Period in timer specific ticks |
| tmo_ev | Timeout event handle |
| EM_OK | Success, event taken |
| EM_ERR_TOONEAR | Failure, the tick value is in past or too close to the current time. Error handler not called, event not taken. |
| (other_codes) | Failure, event not taken. |
Definition at line 1372 of file event_machine_timer.c.
| em_status_t em_tmo_set_periodic_ring | ( | em_tmo_t | tmo, |
| em_timer_tick_t | start_abs, | ||
| uint64_t | multiplier, | ||
| em_event_t | tmo_ev | ||
| ) |
Activate a periodic timeout on a periodic ring timer
Use 'start_abs' value 0 to start the timer relative to current time. To adjust the offset of timeouts, an absolute tick can also be given, but the maximum distance from the current time can only be up to one period. The periodic rate of the timeout event is 'base_hz' (given when creating the timer) multiplied by the given 'multiplier'. For example 1000Hz 'base_hz' with a 'multiplier' of 8 will give a 125us period.
A timeout event of type EM_EVENT_TYPE_TIMER_IND is automatically allocated, if not provided, and will be sent to the queue given to em_tmo_create() when the timeout expires. The user needs to call em_tmo_ack() when receiving the timeout event, similar as with a regular periodic timeout. However, with a ring timer there is no guaranteed flow control - new events may be sent even before user has called em_tmo_ack(). This means that the same event may be in the input queue multiple times if the application can not keep up with the period rate. If the destination queue is not atomic, the same event can also be concurrently received by multiple cores. This is a race hazard the user must prepare for. Additionally, the used timeout event can not be changed via em_tmo_ack(), the actual received event must always be passed to it.
The last argument 'tmo_ev' is normally 'EM_EVENT_UNDEF' when activating a new periodic ring timeout. The implementation will in this case use a pre-allocated event. The exception case concerns reuse of a canceled ring timeout event (when em_tmo_ack() returns 'EM_ERR_CANCELED', the event stays with the user and can be reused). Such an event can be recycled via 'tmo_ev' to avoid an extra event free and alloc during reactivation.
This function can only be used with periodic timeouts from a ring timer. The timeout indication event is read-only and can be accessed only via accessor APIs.
| tmo | Timeout handle |
| start_abs | Absolute start time (or 0 for period starting at call time) |
| multiplier | Rate multiplier (period rate = multiplier * timer base_hz) |
| tmo_ev | Event of type EM_EVENT_TYPE_TIMER_IND to reuse. Normally EM_EVENT_UNDEF. |
| EM_OK | Success |
| EM_ERR_TOONEAR | Failure, start tick value is past or too close to current time or multiplier is too high. |
| EM_ERR_TOOFAR | Failure, start tick value exceeds one period. |
| (other_codes) | Failure |
Definition at line 1457 of file event_machine_timer.c.
| em_status_t em_tmo_set_rel | ( | em_tmo_t | tmo, |
| em_timer_tick_t | ticks_rel, | ||
| em_event_t | tmo_ev | ||
| ) |
Activate a timeout with a relative time.
Similar to em_tmo_set_abs(), but instead of an absolute time uses a timeout value relative to the moment of the call.
This function is for activating oneshot timeouts only. To activate periodic timeouts use em_tmo_set_periodic() (or em_tmo_set_periodic_ring()).
| tmo | Timeout handle |
| ticks_rel | Expiration time in relative timer specific ticks |
| tmo_ev | Timeout event handle |
| EM_OK | Success, event taken. |
| EM_ERR_TOONEAR | Failure, the tick value is too low. Error handler not called, event not taken. |
| (other_codes) | Failure, event not taken. |
Definition at line 1300 of file event_machine_timer.c.
| uint64_t em_tmo_to_u64 | ( | em_tmo_t | tmo | ) |
Convert a timeout handle to an unsigned integer.
| tmo | Timeout handle to be converted. |
Definition at line 1947 of file event_machine_timer.c.