#include <EventQueue.h>
Public Member Functions | |
EventQueue (unsigned size=(32 *(EQUEUE_EVENT_SIZE-2 *sizeof(void *)+sizeof(mbed::Callback< void()>))), unsigned char *buffer=NULL) | |
Create an EventQueue. More... | |
~EventQueue () | |
Destroy an EventQueue. More... | |
void | dispatch_for (duration ms) |
Dispatch events. More... | |
void | dispatch (int ms=-1) |
Dispatch events. More... | |
void | dispatch_forever () |
Dispatch events without a timeout. More... | |
void | dispatch_once () |
Dispatch currently queued events only and then terminate. More... | |
void | break_dispatch () |
Break out of a running event loop. More... | |
unsigned | tick () |
Millisecond counter. More... | |
bool | cancel (int id) |
Cancel an in-flight event. More... | |
template<typename F , typename A > | |
bool | cancel (UserAllocatedEvent< F, A > *event) |
Cancel an in-flight user allocated event. More... | |
int | time_left (int id) |
Query how much time is left for delayed event. More... | |
template<typename F , typename A > | |
int | time_left (UserAllocatedEvent< F, A > *event) |
Query how much time is left for delayed UserAllocatedEvent. More... | |
void | background (mbed::Callback< void(int)> update) |
Background an event queue onto a single-shot timer-interrupt. More... | |
int | chain (EventQueue *target) |
Chain an event queue onto another event queue. More... | |
template<typename F , typename... Args> | |
int | call (F f, Args...args) |
Calls an event on the queue. More... | |
template<typename T , typename R , typename... Args> | |
int | call (T *obj, R(T::*method)(Args...args), Args...args) |
Calls an event on the queue. More... | |
template<typename F , typename... ArgTs> | |
int | call_in (duration ms, F f, ArgTs...args) |
Calls an event on the queue after a specified delay. More... | |
template<typename T , typename R , typename... ArgTs> | |
int | call_in (duration ms, T *obj, R(T::*method)(ArgTs...args), ArgTs...args) |
Calls an event on the queue after a specified delay. More... | |
template<typename F , typename... ArgTs> | |
int | call_every (duration ms, F f, ArgTs...args) |
Calls an event on the queue periodically. More... | |
template<typename T , typename R , typename... ArgTs> | |
int | call_every (duration ms, T *obj, R(T::*method)(ArgTs...args), ArgTs...args) |
Calls an event on the queue periodically. More... | |
template<typename R , typename... BoundArgTs, typename... ContextArgTs, typename... ArgTs> | |
Event< void(ArgTs...)> | event (R(*func)(BoundArgTs..., ArgTs...), ContextArgTs...context_args) |
Creates an event bound to the event queue. More... | |
template<typename T , typename R , typename... BoundArgTs, typename... ContextArgTs, typename... ArgTs> | |
Event< void(ArgTs...)> | event (T *obj, R(T::*method)(BoundArgTs..., ArgTs...), ContextArgTs...context_args) |
Creates an event bound to the event queue. More... | |
template<typename R , typename... BoundArgTs, typename... ContextArgTs, typename... ArgTs> | |
Event< void(ArgTs...)> | event (mbed::Callback< R(BoundArgTs..., ArgTs...)> cb, ContextArgTs...context_args) |
Creates an event bound to the event queue. More... | |
template<typename F , typename... ArgTs> | |
UserAllocatedEvent< F, void(ArgTs...)> | make_user_allocated_event (F f, ArgTs...args) |
Creates an user allocated event bound to the event queue. More... | |
template<typename T , typename R , typename... ArgTs> | |
UserAllocatedEvent< mbed::Callback< void(ArgTs...)>, void(ArgTs...)> | make_user_allocated_event (T *obj, R(T::*method)(ArgTs...args), ArgTs...args) |
Creates an user allocated event bound to the event queue. More... | |
EventQueue | ( | unsigned | size = (32 *(EQUEUE_EVENT_SIZE-2 *sizeof(void *)+sizeof(mbed::Callback< void()>))) , |
unsigned char * | buffer = NULL |
||
) |
Create an EventQueue.
Create an event queue. The event queue either allocates a buffer of the specified size with malloc or uses the user provided buffer or uses 1B dummy buffer if 0 size passed.
0 size queue is a special purpose queue to dispatch static events only (see UserAllocatedEvent). Such a queue gives the guarantee that no dynamic memory allocation will take place while queue creation and events posting & dispatching.
size | Size of buffer to use for events in bytes (default to EVENTS_QUEUE_SIZE) If 0 provided then 1B dummy buffer is used |
buffer | Pointer to buffer to use for events (default to NULL) |
~EventQueue | ( | ) |
Destroy an EventQueue.
void background | ( | mbed::Callback< void(int)> | update | ) |
Background an event queue onto a single-shot timer-interrupt.
When updated, the event queue will call the provided update function with a timeout indicating when the queue should be dispatched. A negative timeout will be passed to the update function when the timer-interrupt is no longer needed.
Passing a null function disables the existing update function.
The background function allows an event queue to take advantage of hardware timers or other event loops, allowing an event queue to be ran in the background without consuming the foreground thread.
update | Function called to indicate when the queue should be dispatched |
void break_dispatch | ( | ) |
Break out of a running event loop.
Forces the specified event queue's dispatch loop to terminate. Pending events may finish executing, but no new events will be executed.
int call | ( | F | f, |
Args... | args | ||
) |
Calls an event on the queue.
The specified callback will be executed in the context of the event queue's dispatch loop.
The call function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
f | Function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
int call | ( | T * | obj, |
R(T::*)(Args...args) | method, | ||
Args... | args | ||
) |
Calls an event on the queue.
The specified callback is executed in the context of the event queue's dispatch loop.
The call function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
obj | Object to call with the member function |
method | Member function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
int call_every | ( | duration | ms, |
F | f, | ||
ArgTs... | args | ||
) |
Calls an event on the queue periodically.
The specified callback is executed in the context of the event queue's dispatch loop.
The call_every function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
ms | Period of the event in milliseconds |
f | Function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
int call_every | ( | duration | ms, |
T * | obj, | ||
R(T::*)(ArgTs...args) | method, | ||
ArgTs... | args | ||
) |
Calls an event on the queue periodically.
The specified callback is executed in the context of the event queue's dispatch loop.
The call_every function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
ms | Period of the event in milliseconds |
obj | Object to call with the member function |
method | Member function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
int call_in | ( | duration | ms, |
F | f, | ||
ArgTs... | args | ||
) |
Calls an event on the queue after a specified delay.
The specified callback is executed in the context of the event queue's dispatch loop.
The call_in function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
ms | Time to delay in milliseconds |
f | Function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
int call_in | ( | duration | ms, |
T * | obj, | ||
R(T::*)(ArgTs...args) | method, | ||
ArgTs... | args | ||
) |
Calls an event on the queue after a specified delay.
The specified callback is executed in the context of the event queue's dispatch loop.
The call_in function is IRQ safe and can act as a mechanism for moving events out of IRQ contexts.
ms | Time to delay in milliseconds |
obj | Object to call with the member function |
method | Member function to execute in the context of the dispatch loop |
args | Arguments to pass to the callback |
bool cancel | ( | int | id | ) |
Cancel an in-flight event.
Attempts to cancel an event referenced by the unique id returned from one of the call functions. It is not safe to call cancel after an event has already been dispatched.
id must be valid i.e. event must have not finished executing.
The cancel function is IRQ safe.
If called while the event queue's dispatch loop is active in another thread, the cancel function does not guarantee that the event will not execute after it returns, as the event may have already begun executing. A call made from the same thread as the dispatch loop will always succeed with a valid id.
id | Unique id of the event |
bool cancel | ( | UserAllocatedEvent< F, A > * | event | ) |
Cancel an in-flight user allocated event.
Attempts to cancel an UserAllocatedEvent referenced by its address It is not safe to call cancel after an event has already been dispatched.
Event must be valid i.e. event must have not finished executing and must have been bound to this queue.
The cancel function is IRQ safe.
If called while the event queue's dispatch loop is active in another thread, the cancel function does not guarantee that the event will not execute after it returns, as the event may have already begun executing. A call made from the same thread as the dispatch loop will always succeed with a valid id.
event | Address of the event |
Definition at line 195 of file EventQueue.h.
int chain | ( | EventQueue * | target | ) |
Chain an event queue onto another event queue.
After chaining a queue to a target, calling dispatch on the target queue will also dispatch events from this queue. The queues use their own buffers and events must be handled independently.
A null queue as the target will unchain the existing queue.
The chain function allows multiple event queues to be composed, sharing the context of a dispatch loop while still being managed independently
target | Queue that will dispatch this queue's events as a part of its dispatch loop |
void dispatch | ( | int | ms = -1 | ) |
Dispatch events.
Executes events until the specified milliseconds have passed. If ms is negative, the dispatch function will dispatch events indefinitely or until break_dispatch is called on this queue.
When called with a finite timeout, the dispatch function is guaranteed to terminate. When called with a timeout of 0, the dispatch function does not wait and is IRQ safe.
NOTE: Since the majority of the event library was updated to use Chrono types (as part of the Mbed 6 release), this function will not function as expected. Please update to use the new dispatch functions to ensure correct functionality.
ms | Time to wait for events in milliseconds, a negative value will dispatch events indefinitely (default to -1) |
void dispatch_for | ( | duration | ms | ) |
Dispatch events.
Executes events for the specified number of milliseconds.
The dispatch_for() function is guaranteed to terminate after the elapsed wait.
ms | Time to wait for events in milliseconds, expressed as a Chrono duration. |
void dispatch_forever | ( | ) |
Dispatch events without a timeout.
Executes events indefinitely unless the dispatch loop is forcibly broken. break_dispatch()
void dispatch_once | ( | ) |
Dispatch currently queued events only and then terminate.
In this case the dispatch function does not wait.
Event<void(ArgTs...)> event | ( | R(*)(BoundArgTs..., ArgTs...) | func, |
ContextArgTs... | context_args | ||
) |
Creates an event bound to the event queue.
Constructs an event bound to the specified event queue. The specified callback acts as the target for the event and is executed in the context of the event queue's dispatch loop once posted.
func | Function to execute when the event is dispatched |
context_args | Arguments to pass to the callback |
Event<void(ArgTs...)> event | ( | T * | obj, |
R(T::*)(BoundArgTs..., ArgTs...) | method, | ||
ContextArgTs... | context_args | ||
) |
Creates an event bound to the event queue.
Constructs an event bound to the specified event queue. The specified callback acts as the target for the event and is executed in the context of the event queue's dispatch loop once posted.
obj | Object to call with the member function |
method | Member function to execute in the context of the dispatch loop |
context_args | Arguments to pass to the callback |
Event<void(ArgTs...)> event | ( | mbed::Callback< R(BoundArgTs..., ArgTs...)> | cb, |
ContextArgTs... | context_args | ||
) |
Creates an event bound to the event queue.
Constructs an event bound to the specified event queue. The specified callback acts as the target for the event and is executed in the context of the event queue's dispatch loop once posted.
cb | Callback object |
context_args | Arguments to pass to the callback |
unsigned tick | ( | ) |
Millisecond counter.
Returns the underlying tick of the event queue represented as the number of milliseconds that have passed since an arbitrary point in time. Intentionally overflows to 0 after 2^32-1.
int time_left | ( | int | id | ) |
Query how much time is left for delayed event.
If the event is delayed, this function can be used to query how much time is left until the event is due to be dispatched.
id must be valid i.e. event must have not finished executing.
This function is IRQ safe.
id | Unique id of the event |
int time_left | ( | UserAllocatedEvent< F, A > * | event | ) |
Query how much time is left for delayed UserAllocatedEvent.
If the event is delayed, this function can be used to query how much time is left until the event is due to be dispatched.
Event must be valid i.e. event must have not finished executing and must have been bound to this queue.
This function is IRQ safe.
event | Address of the event |
Definition at line 241 of file EventQueue.h.