Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Member Functions | Static Protected Member Functions | Protected Attributes | Friends
events::EventQueue Class Reference

#include <EventQueue.h>

Inheritance diagram for events::EventQueue:
mbed::NonCopyable< EventQueue >

Data Structures

struct  context00
 
struct  context01
 
struct  context02
 
struct  context03
 
struct  context04
 
struct  context05
 
struct  context10
 
struct  context11
 
struct  context12
 
struct  context13
 
struct  context14
 
struct  context15
 
struct  context20
 
struct  context21
 
struct  context22
 
struct  context23
 
struct  context24
 
struct  context25
 
struct  context30
 
struct  context31
 
struct  context32
 
struct  context33
 
struct  context34
 
struct  context35
 
struct  context40
 
struct  context41
 
struct  context42
 
struct  context43
 
struct  context44
 
struct  context45
 
struct  context50
 
struct  context51
 
struct  context52
 
struct  context53
 
struct  context54
 
struct  context55
 

Public Member Functions

 EventQueue (unsigned size=(32 *((sizeof(struct equeue_event)+2 *sizeof(void *))-2 *sizeof(void *)+sizeof(mbed::Callback< void()>))), unsigned char *buffer=NULL)
 
 ~EventQueue ()
 
void dispatch (int ms=-1)
 
void dispatch_forever ()
 
void break_dispatch ()
 
unsigned tick ()
 
void cancel (int id)
 
int time_left (int id)
 
void background (mbed::Callback< void(int)> update)
 
void chain (EventQueue *target)
 
template<typename F , typename... Args>
int call (F f, Args...args)
 
template<typename T , typename R , typename... Args>
int call (T *obj, R(T::*method)(Args...args), Args...args)
 
template<typename F , typename... Args>
int call_in (int ms, Args...args)
 
template<typename T , typename R , typename... Args>
int call_in (int ms, T *obj, R(T::*method)(Args...args), Args...args)
 
template<typename F , typename... Args>
int call_every (int ms, F f, Args...args)
 
template<typename T , typename R , typename... Args>
int call_every (int ms, T *obj, R(T::*method)(Args...args), Args...args)
 
template<typename R , typename... BoundArgs, typename... Args>
Event< void(Args...)> event (R(*func)(BoundArgs...), Args...args)
 
template<typename T , typename R , typename... BoundArgs, typename... ContextArgs, typename... Args>
Event< void(Args...)> event (T *obj, R(T::*method)(BoundArgs..., Args...), ContextArgs...context_args)
 
template<typename R , typename... BoundArgs, typename... ContextArgs, typename... Args>
Event< void(Args...)> event (mbed::Callback< R(BoundArgs..., Args...)> cb, ContextArgs...context_args)
 

Static Protected Member Functions

template<typename F >
static void function_call (void *p)
 
template<typename F >
static void function_dtor (void *p)
 

Protected Attributes

struct equeue _equeue
 
mbed::Callback< void(int)> _update
 

Friends

template<typename F >
class Event
 

Detailed Description

EventQueue

Flexible event queue for dispatching events

Constructor & Destructor Documentation

events::EventQueue::EventQueue ( unsigned  size = (32* ( (sizeof(struct equeue_event) + 2*sizeof(void*))  - 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.

Parameters
sizeSize of buffer to use for events in bytes (default to EVENTS_QUEUE_SIZE)
bufferPointer to buffer to use for events (default to NULL)
events::EventQueue::~EventQueue ( )

Destroy an EventQueue

Member Function Documentation

void events::EventQueue::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.

Parameters
updateFunction called to indicate when the queue should be dispatched
void events::EventQueue::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.

template<typename F , typename... Args>
int events::EventQueue::call ( 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.

Parameters
fFunction to execute in the context of the dispatch loop
argsArguments to pass to the callback
Returns
A unique id that represents the posted event and can be passed to cancel, or an id of 0 if there is not enough memory to allocate the event. Returned id will remain valid until event has finished executing.
#include "mbed.h"
int main() {
// creates a queue with the default size
EventQueue queue;
// events are simple callbacks
queue.call(printf, "called immediately\n");
// the dispatch method executes events
queue.dispatch();
}
template<typename T , typename R , typename... Args>
int events::EventQueue::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.

Parameters
objObject to call with the member function
methodMember function to execute in the context of the dispatch loop
argsArguments to pass to the callback
Returns
A unique ID that represents the posted event and can be passed to cancel, or an ID of 0 if there is not enough memory to allocate the event. Returned ID remains valid until event has finished executing.
#include "mbed.h"
class EventHandler {
int _id;
public:
EventHandler(int id) : _id(id) { }
void handler(int c) {
printf("ID: %d Param: %d\r\n", _id, c);
}
};
int main() {
// creates a queue with the default size
EventQueue queue;
// Create EventHandler object with state
EventHandler handler_cb(1);
// events are simple callbacks, call object method
// with provided parameter
queue.call(&handler_cb, &EventHandler::handler, 2);
// the dispath method executes events
queue.dispatch();
}
template<typename F , typename... Args>
int events::EventQueue::call_every ( int  ms,
f,
Args...  args 
)

Calls an event on the queue periodically

Note
The first call_every event occurs after the specified delay. To create a periodic event that fires immediately,
See also
Event.

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.

Parameters
msPeriod of the event in milliseconds
fFunction to execute in the context of the dispatch loop
argsArguments to pass to the callback
Returns
A unique ID that represents the posted event and can be passed to cancel, or an ID of 0 if there is not enough memory to allocate the event.
#include "mbed.h"
class EventHandler {
int _id;
public:
EventHandler(int id) : _id(id) { }
void handler(int c) {
printf("ID: %d Param: %d\r\n", _id, c);
}
};
int main() {
// creates a queue with the default size
EventQueue queue;
// events are simple callbacks, call every 2 seconds
queue.call_every(2000, printf, "Calling every 2 seconds\n");
// the dispatch method executes events
queue.dispatch();
}
template<typename T , typename R , typename... Args>
int events::EventQueue::call_every ( int  ms,
T *  obj,
R(T::*)(Args...args)  method,
Args...  args 
)

Calls an event on the queue periodically

Note
The first call_every event occurs after the specified delay. To create a periodic event that fires immediately,
See also
Event.

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.

Parameters
msPeriod of the event in milliseconds
objObject to call with the member function
methodMember function to execute in the context of the dispatch loop
argsArguments to pass to the callback
#include "mbed.h"
class EventHandler {
int _id;
public:
EventHandler(int id) : _id(id) { }
void handler(int c) {
printf("ID: %d Param: %d\r\n", _id, c);
}
};
int main() {
// creates a queue with the default size
EventQueue queue;
// Create EventHandler object with state
EventHandler handler_cb(5);
// events are simple callbacks, call object method every 2 seconds
// with provided parameter
queue.call_every(2000, &handler_cb, &EventHandler::handler, 6);
// the dispatch method executes events
queue.dispatch();
}
template<typename F , typename... Args>
int events::EventQueue::call_in ( int  ms,
Args...  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.

Parameters
msTime to delay in milliseconds
argsArguments to pass to the callback
Returns
A unique ID that represents the posted event and can be passed to cancel, or an ID of 0 if there is not enough memory to allocate the event.
#include "mbed.h"
int main() {
// creates a queue with the default size
EventQueue queue;
// events are simple callbacks
queue.call_in(2000, printf, "called in 2 seconds\n");
// the dispatch methods executes events
queue.dispatch();
}
template<typename T , typename R , typename... Args>
int events::EventQueue::call_in ( int  ms,
T *  obj,
R(T::*)(Args...args)  method,
Args...  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.

Parameters
msTime to delay in milliseconds
objObject to call with the member function
methodMember function to execute in the context of the dispatch loop
argsArguments to pass to the callback
Returns
A unique ID that represents the posted event and can be passed to cancel, or an ID of 0 if there is not enough memory to allocate the event.
#include "mbed.h"
class EventHandler {
int _id;
public:
EventHandler(int id) : _id(id) { }
void handler(int c) {
printf("ID: %d Param: %d\r\n", _id, c);
}
};
int main() {
// creates a queue with the default size
EventQueue queue;
// Create EventHandler object with state
EventHandler handler_cb(3);
// events are simple callbacks, call object method in 2 seconds
// with provided parameter
queue.call_in(2000, &handler_cb, &EventHandler::handler, 4);
// the dispatch method executes events
queue.dispatch();
}
void events::EventQueue::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 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, the cancel function does not guarantee that the event will not execute after it returns, as the event may have already begun executing.

Parameters
idUnique id of the event
void events::EventQueue::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

Parameters
targetQueue that will dispatch this queue's events as a part of its dispatch loop
void events::EventQueue::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.

Parameters
msTime to wait for events in milliseconds, a negative value will dispatch events indefinitely (default to -1)
void events::EventQueue::dispatch_forever ( )
inline

Dispatch events without a timeout

This is equivalent to EventQueue::dispatch with no arguments, but avoids overload ambiguities when passed as a callback.

See also
EventQueue::dispatch
template<typename R , typename... BoundArgs, typename... Args>
Event<void(Args...)> events::EventQueue::event ( R(*)(BoundArgs...)  func,
Args...  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.

Parameters
funcFunction to execute when the event is dispatched
argsArguments to pass to the callback
Returns
Event that dispatches on the specific queue
#include "mbed.h"
void handler(int c) {
printf("Param: %d\r\n", c);
}
int main()
{
EventQueue queue;
// Create event with parameter
Event<void()> e = queue.event(handler, 1);
e();
// Create event and post parameter later
Event<void(int)> e2 = queue.event(handler);
// Post the event with paramter 8
e.post(8);
// The dispatch method executes events
queue.dispatch();
e2.post(2);
queue.dispatch();
}
template<typename T , typename R , typename... BoundArgs, typename... ContextArgs, typename... Args>
Event<void(Args...)> events::EventQueue::event ( T *  obj,
R(T::*)(BoundArgs..., Args...)  method,
ContextArgs...  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.

Parameters
objObject to call with the member function
methodMember function to execute in the context of the dispatch loop
context_argsArguments to pass to the callback
Returns
Event that dispatches on the specific queue
#include "mbed.h"
class EventHandler {
int _id;
public:
EventHandler(int id) : _id(id) { }
void handler(int c) {
printf("ID: %d Param: %d\r\n", _id, c);
}
};
int main()
{
EventQueue queue;
EventHandler handler_cb(10);
// Create event on the eventqueue with a method callback
Event<void(int)> e = queue.event(&handler_cb, &EventHandler::handler);
// Post the event with paramter 8
e.post(11);
// The dispatch method executes events
queue.dispatch();
}
template<typename R , typename... BoundArgs, typename... ContextArgs, typename... Args>
Event<void(Args...)> events::EventQueue::event ( mbed::Callback< R(BoundArgs..., Args...)>  cb,
ContextArgs...  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.

Parameters
cbCallback object
context_argsArguments to pass to the callback
Returns
Event that dispatches on the specific queue
#include "mbed.h"
void handler(int c) {
printf("Param: %d\r\n", c);
}
int main()
{
EventQueue queue;
// Create callback object acting as a function
// pointer to handler
Callback<void(int)> cb(handler);
// Pass the callback object to the eventqueue
Event<void(int)> e = queue.event(cb);
// Post the event with parameter 8
e.post(9);
// The dispatch method executes events
q.dispatch();
}
unsigned events::EventQueue::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.

Returns
The underlying tick of the event queue in milliseconds
int EventQueue::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.

Parameters
idUnique id of the event
Returns
Remaining time in milliseconds or 0 if event is already due to be dispatched or is currently executing. Undefined if id is invalid.

The documentation for this class was generated from the following files:
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.