EM-ODP
3.7.0
Event Machine on ODP
|
Event Machine timer. More...
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 |
Macros | |
#define | EM_TIMER_API_VERSION_MAJOR EM_API_VERSION_MAJOR |
#define | EM_TIMER_API_VERSION_MINOR EM_API_VERSION_MINOR |
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.
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 re-used after it has been received or 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. Tick frequency is at least equal to the resolution, but can also be higher (implementation can quantize ticks to any underlying implementation). 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.
The major event types EM_EVENT_TYPE_SW, EM_EVENT_TYPE_PACKET and EM_EVENT_TYPE_TIMER can be used as a timeout indication. The type EM_EVENT_TYPE_TIMER is alternative to EM_EVENT_TYPE_SW and works the same way. Additionally for ring timer only, the type EM_EVENT_TYPE_TIMER_IND is used. This is a special indication event without visible payload.
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 with the acknowledge. 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. Application also needs to have a mechanism to detect which event is a periodic timeout to be able to call acknowledge.
If the timeout tick value given to timeout start points to the past or is too close to current time then error code EM_ERR_TOONEAR is returned. In this case EM will not call error handler to let application decide whether it is an error or if it will try again with updated target time.
There is an alternative periodic ring timer. As it uses different abstraction it is created and started via separate ring specific APIs. It has three main differencies to the regular periodic timeouts:
Ring timers can be abstracted 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), the regular periodic timer is recommended as a default.
Example usage
#define EM_TIMER_API_VERSION_MAJOR EM_API_VERSION_MAJOR |
Deprecated Major EM Timer API version. Marks possibly backwards incompatible changes. EM timer is now part of EM API. Use EM_API_VERSION_MAJOR instead.
Definition at line 196 of file api/event_machine_timer.h.
#define EM_TIMER_API_VERSION_MINOR EM_API_VERSION_MINOR |
Deprecated Minor EM Timer API version. Marks possibly backwards incompatible changes. EM Timer is now part of EM API. Use EM_API_VERSION_MINOR instead.
Definition at line 201 of file api/event_machine_timer.h.
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 |
Structure used to create a timer or inquire 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 are considered a requirement, e.g. setting 'resparam.res_ns' to 1000(ns) requires at least 1us resolution. The timer creation will fail if the implementation cannot support such resolution (like 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 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 ns.
typedef struct em_timer_ring_param_t em_timer_ring_param_t |
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 261 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 | oneshot expired |
Definition at line 240 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 timer-related event |
EM_TMO_TYPE_ONESHOT | event is oneshot timeout indication |
EM_TMO_TYPE_PERIODIC | event is periodic timeout indication |
Definition at line 250 of file api/event_machine_timer.h.
void em_timer_attr_init | ( | em_timer_attr_t * | tmr_attr | ) |
Initialize em_timer_attr_t
Initializes em_timer_attr_t to system specific default values. After initialization user can adjust the values as needed before calling em_timer_create. 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 any use.
This function will not trigger errorhandler 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 errorhandler 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'. 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 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 | ) |
Returns 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, frees all resources. All timeouts for this timer must have been 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 1754 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 1778 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 tick.
tmr | Timer handle |
Definition at line 1823 of file event_machine_timer.c.
em_timer_tick_t em_timer_ns_to_tick | ( | em_timer_t | tmr, |
uint64_t | ns | ||
) |
Convert ns to timer tick
tmr | Valid timer handle |
ns | ns value to convert |
Definition at line 1850 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 given resolution or maximum timeout. Set one of resolution (res.res_ns) or maximum timeout (res.max_tmo) to required value and the other to zero and this will fill the other fields with valid limits. 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 this is passed to em_timer_create, one of those must be set to 0.
Example for external clock maximum resolution
This function will not trigger errorhandler 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_ring_attr_t
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 exact given combination it may update the ring_attr values, but always to meet or exceed given value. User can read the new values to determine if they were modified. Error is returned if given values cannot be met.
Before creating the ring timer other values like num_tmo and name can be adjusted as needed. Also if non-integer frequency is needed the base_hz fractional part can be adjusted before timer_ring_create.
This function will not trigger errorhandler 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 timing 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 ring timer capability from given input values. On input parameter ring must be initialized with the required values. res_ns can be 0, which gets replaced by the system default. During the call values are updated. If this returns EM_OK 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 errorhandler call from timer_ring_create().
This function will not trigger errorhandler 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 timer ring (alternative periodic timer)
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 different and will only send EM_EVENT_TYPE_TIMER_IND 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 tick to ns
tmr | Valid timer handle |
ticks | Timer specific ticks to convert |
Definition at line 1837 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 1968 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 re-used 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. Application can alter this behaviour with the flag EM_TMO_FLAG_NOSKIP when creating a timeout. Then no past timeout is skipped and each late acknowledgment will immediately trigger sending the next timeout event until 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 errorhandler.
If the timer has been canceled, but the cancel happened too late for the current period the timeout will be delivered. If application then calls em_tmo_ack it returns EM_ERR_CANCELED and does not call errorhandler. This is to signal it was the last timeout coming for that tmo.
Application may re-use the same received timeout event or provide a new one for the next timeout. With ring timer the received event must be returned.
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.
Periodic timeout will stop if em_tmo_ack() returns an error other than timing related. The implementation will call errorhandler in this case unless timer was canceled, so the 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) |
EM_OK | success (event taken) |
EM_ERR_CANCELED | timer has been cancelled, no more coming, not taken |
(other_codes) | failure, event not taken |
Definition at line 1638 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 in case the timeout was not expired. A timeout that has already expired or just about to cannot be cancelled and the timeout event will be delivered to the destination queue. In this case cancel will return an error as it was too late to cancel. Errorhandler is not called if failure is due to expired timeout only.
Periodic timeout: cancel may fail if attempted too close to the next period. This can be considered normal and indicates that one more timeout will be received. In this case errorhandler is not called, error status EM_ERR_TOONEAR returned and no event returned. When em_tmo_ack is then called on the canceled timeout event receive it will return EM_ERR_CANCELED to indicate this is the last event coming for this timeout.
tmo | Timeout handle | |
[out] | cur_event | Event handle pointer to return the pending timeout event or EM_EVENT_UNDEF if cancel fails (e.g. called too late) |
EM_OK | success, event returned |
EM_ERR_TOONEAR | already expired (too late to cancel). Errorhandler not called |
(other_codes) | failure |
Definition at line 1563 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. LOCAL or OUTPUT queues can not be used as timeout targets. Support for unscheduled queues is implementation specific.
Flags are used to select functionality:
If used timer is timer ring the NOSKIP flag is ignored.
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
Like em_tmo_create but with additional argument. This can be used with any timer type, but e.g. the userptr argument is only used with ring timers using events of type EM_EVENT_TYPE_TIMER_IND that can carry 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, |
em_event_t * | cur_event | ||
) |
Free a timeout
Free (destroy) a timeout. The user provided timeout event for an active timeout will be returned via cur_event and the timeout is cancelled. The timeout event for an expired, but not yet received timeout will not be returned. It is the responsibility of the application to handle that case (event will still be received).
After and during this call the tmo handle is not valid anymore and must not be used. With periodic timeout means em_tmo_ack must also not be called when tmo is deleted.
tmo | Timeout handle | |
[out] | cur_event | Current event for an active timeout |
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 1863 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 1877 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
Associated timer handle is returned from a valid timeout. Can be used to for instance read the current timer tick without having the timer handle:
tmo | valid timeout handle |
Definition at line 1954 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 given event is currently used as timeout indication.
This can be used with any valid event handle to ask if it is used as a timeout indication event. Events are updated for tmo type when going through timer API.
Successful timeout cancel (event returned) will reset the event type to EM_TMO_TYPE_NONE.
The related tmo handle can also be retrieved via parameter tmo. This can be useful to call em_tmo_ack() for periodic timeouts:
event | event handle to check | |
[out] | tmo | pointer to em_tmo_t to receive related tmo handle (NULL ok) |
reset | set true to reset tmo type to EM_TMO_TYPE_NONE for non-timer re-use |
Definition at line 1900 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 for a periodic ring, i.e. 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 1933 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 oneshot timeout to expire at 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).
Allowed minimum and maximum timeout 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 re-used by calling em_tmo_set_abs/rel() again after the previous timeout was received or was cancelled successfully.
This function is for activating oneshot timeouts only. To activate a periodic timer use em_tmo_set_periodic() instead.
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, tick value is in past or too close to current time. Errorhandler not called, event not taken |
(other_codes) | failure, event not taken |
Definition at line 1255 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 e.g. the first period starts from that moment. Use 0 as start time if the period can start from the moment of the call (relative).
The timeout event will be sent to the queue given to em_tmo_create() when the first timeout expires. Receiver then need to call em_tmo_ack() to allow sending next event.
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, tick value is in past or too close to current time. Errorhandler not called, event not taken |
(other_codes) | failure, event not taken |
Definition at line 1402 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 current time can only be up to one period. 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 multiplier of 8 will give 125us period.
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. User then needs to call em_timer_ack like with normal periodic timeout. With ring timer however there is no guaranteed flow control, new events may be sent even before user has called ack. This means the same event may be in the input queue multiple times if the application can not keep up the period rate. If the destination queue is not atomic the same event can then also be concurrently received by multiple cores. This is a race hazard to prepare for. Additionally the used event can not change via em_tmo_ack, the received event must always be returned.
The last argument tmo_ev is normally EM_EVENT_UNDEF for a new timeout start. Then the implementation will use pre-allocated event. Exception is re-use of canceled ring timeout event (when ack returns EM_ERR_CANCELED the event stays with user and can be re-used). Such event can be recycled here to avoid extra free and alloc.
This function can only be used with periodic timeouts with 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 re-use. 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 1487 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 relative time.
Similar to em_tmo_set_abs(), but instead of an absolute time uses timeout value relative to the moment of the call.
This function is for activating oneshot timeouts only. To activate a periodic timer use em_tmo_set_periodic() instead.
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, tick value is too low. Errorhandler not called, event not taken |
(other_codes) | failure, event not taken |
Definition at line 1330 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 1973 of file event_machine_timer.c.