diff --git a/events/Event.h b/events/Event.h index a704409bf8b..a5f5f2b8ff3 100644 --- a/events/Event.h +++ b/events/Event.h @@ -1890,6 +1890,7 @@ class Event { } public: +#if !defined(DOXYGEN_ONLY) /** Create an event * @param q Event queue to dispatch on * @param f Function to execute when the event is dispatched @@ -3619,7 +3620,7 @@ template EventQueue::event(mbed::Callback cb, C0 c0, C1 c1, C2 c2, C3 c3, C4 c4) { return Event(this, cb, c0, c1, c2, c3, c4); } - +#endif } #endif diff --git a/events/EventQueue.h b/events/EventQueue.h index 01ab02a6d53..fc2c49318bc 100644 --- a/events/EventQueue.h +++ b/events/EventQueue.h @@ -84,7 +84,7 @@ class EventQueue : private mbed::NonCopyable { /** Dispatch events without a timeout * - * This is equivalent to EventQueue::dispatch with no arguments, but + * This is equivalent to EventQueue::dispatch with no arguments, but * avoids overload ambiguities when passed as a callback. * * @see EventQueue::dispatch @@ -100,7 +100,7 @@ class EventQueue : private mbed::NonCopyable { /** Millisecond counter * - * Returns the underlying tick of the event queue represented as the + * 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. * @@ -180,6 +180,9 @@ class EventQueue : private mbed::NonCopyable { */ void chain(EventQueue *target); + + + #if defined(DOXYGEN_ONLY) /** Calls an event on the queue * * The specified callback will be executed in the context of the event @@ -189,11 +192,412 @@ class EventQueue : private mbed::NonCopyable { * events out of irq contexts. * * @param f Function to execute in the context of the dispatch loop + * @param args Arguments to pass to the callback * @return 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. + * + * @code + * #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(); + * } + * @endcode + */ + template + int call(F f, 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. + * + * @param obj Object to call with the member function + * @param method Member function to execute in the context of the dispatch loop + * @param args Arguments to pass to the callback + * @return 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. + * + * @code + * #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(); + * } + * @endcode + */ + template + int call(T *obj, R (T::*method)(Args ...args), 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. + * + * @param ms Time to delay in milliseconds + * @param args Arguments to pass to the callback + * @return 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. + * + * @code + * #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(); + * } + * @endcode + */ + template + int 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. + * + * @param ms Time to delay in milliseconds + * @param obj Object to call with the member function + * @param method Member function to execute in the context of the dispatch loop + * @param args Arguments to pass to the callback + * @return 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. + * + * @code + * #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(); + * } + * @endcode + */ + template + int call_in(int ms, T *obj, R (T::*method)(Args ...args), 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 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. + * + * @param ms Period of the event in milliseconds + * @param f Function to execute in the context of the dispatch loop + * @param args Arguments to pass to the callback + * @return 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. + * + * @code + * #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(); + * } + * @endcode + */ + template + int call_every(int ms, F 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 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. + * + * @param ms Period of the event in milliseconds + * @param obj Object to call with the member function + * @param method Member function to execute in the context of the dispatch loop + * @param args Arguments to pass to the callback + * + * @code + * #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(); + * } + * @endcode + */ + template + int call_every(int ms, T *obj, R (T::*method)(Args ...args), 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. + * + * @param func Function to execute when the event is dispatched + * @param args Arguments to pass to the callback + * @return Event that dispatches on the specific queue + * + * @code + * #include "mbed.h" + * + * void handler(int c) { + * printf("Param: %d\r\n", c); + * } + * + * int main() + * { + * EventQueue queue; + * + * // Create event with parameter + * Event e = queue.event(handler, 1); + * e(); + * + * // Create event and post parameter later + * Event 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(); + * } + * @endcode + */ + template + Event event(R (*func)(BoundArgs...), 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. + * + * @param obj Object to call with the member function + * @param method Member function to execute in the context of the dispatch loop + * @param context_args Arguments to pass to the callback + * @return Event that dispatches on the specific queue + * + * @code + * #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 e = queue.event(&handler_cb, &EventHandler::handler); + * + * // Post the event with paramter 8 + * e.post(11); + * + * // The dispatch method executes events + * queue.dispatch(); + * } + * @endcode + */ + template + Event event(T *obj, R (T::*method)(BoundArgs..., Args...), 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. + * + * @param cb Callback object + * @param context_args Arguments to pass to the callback + * @return Event that dispatches on the specific queue + * + * @code + * #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 cb(handler); + * + * // Pass the callback object to the eventqueue + * Event e = queue.event(cb); + * + * // Post the event with parameter 8 + * e.post(9); + * + * // The dispatch method executes events + * q.dispatch(); + * } + * @endcode + */ + template + Event event(mbed::Callback cb, ContextArgs ...context_args); + + #else + + /** 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. + * + * @param f Function to execute in the context of the dispatch loop + * @return 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. + * + * @code + * #include "mbed.h" + * + * int main() + * { + * EventQueue queue; + * + * Callback cb(handler); + * + * // Create event on the eventqueue with a separate callback object + * Event e = queue.event(cb); + * e.post(1); + * queue.dispatch(); + * } + * @endcode */ template int call(F f) { @@ -207,6 +611,7 @@ class EventQueue : private mbed::NonCopyable { return equeue_post(&_equeue, &EventQueue::function_call, e); } + /** Calls an event on the queue * @see EventQueue::call * @param f Function to execute in the context of the dispatch loop @@ -457,8 +862,8 @@ class EventQueue : private mbed::NonCopyable { * The call_in function is irq safe and can act as a mechanism for moving * events out of irq contexts. * - * @param f Function to execute in the context of the dispatch loop * @param ms Time to delay in milliseconds + * @param f Function to execute in the context of the dispatch loop * @return 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. @@ -2302,6 +2707,7 @@ class EventQueue : private mbed::NonCopyable { */ template Event event(mbed::Callback cb, C0 c0, C1 c1, C2 c2, C3 c3, C4 c4); + #endif protected: template