diff --git a/events/include/events/EventQueue.h b/events/include/events/EventQueue.h index 1bcc018..97b898f 100644 --- a/events/include/events/EventQueue.h +++ b/events/include/events/EventQueue.h @@ -88,6 +88,17 @@ /** Dispatch events * + * Executes events for the specified number of milliseconds. + * + * The dispatch_for() function is guaranteed to terminate after the elapsed wait. + * + * @param ms Time to wait for events in milliseconds, expressed as a + * Chrono duration. + */ + void dispatch_for(duration ms); + + /** 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. @@ -96,23 +107,32 @@ * 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. + * * @param ms Time to wait for events in milliseconds, a negative * value will dispatch events indefinitely * (default to -1) */ + MBED_DEPRECATED_SINCE("mbed-os-6.7.0", "Use dispatch_for() to pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.") void dispatch(int ms = -1); /** Dispatch events without a timeout * - * This is equivalent to EventQueue::dispatch with no arguments, but - * avoids overload ambiguities when passed as a callback. + * Executes events indefinitely unless the dispatch loop is forcibly broken. + * @See break_dispatch() * - * @see EventQueue::dispatch */ - void dispatch_forever() - { - dispatch(); - } + void dispatch_forever(); + + /** Dispatch currently queued events only and then terminate + * + * In this case the dispatch function does not wait. + * + */ + void dispatch_once(); /** Break out of a running event loop * diff --git a/events/source/EventQueue.cpp b/events/source/EventQueue.cpp index a64440e..7957049 100644 --- a/events/source/EventQueue.cpp +++ b/events/source/EventQueue.cpp @@ -41,11 +41,26 @@ equeue_destroy(&_equeue); } +void EventQueue::dispatch_for(duration ms) +{ + return equeue_dispatch(&_equeue, ms.count()); +} + void EventQueue::dispatch(int ms) { return equeue_dispatch(&_equeue, ms); } +void EventQueue::dispatch_forever() +{ + return equeue_dispatch(&_equeue, -1); +} + +void EventQueue::dispatch_once() +{ + return equeue_dispatch(&_equeue, 0); +} + void EventQueue::break_dispatch() { return equeue_break(&_equeue); diff --git a/events/tests/TESTS/events/queue/main.cpp b/events/tests/TESTS/events/queue/main.cpp index 59c9449..d19ecd8 100644 --- a/events/tests/TESTS/events/queue/main.cpp +++ b/events/tests/TESTS/events/queue/main.cpp @@ -89,17 +89,17 @@ \ touched = false; \ queue.call(func##i,##__VA_ARGS__); \ - queue.dispatch(0); \ + queue.dispatch_once(); \ TEST_ASSERT(touched); \ \ touched = false; \ - queue.call_in(1ms, func##i,##__VA_ARGS__); \ - queue.dispatch(2); \ + queue.call_in(1ms, func##i,##__VA_ARGS__); \ + queue.dispatch_for(2ms); \ TEST_ASSERT(touched); \ \ touched = false; \ - queue.call_every(1ms, func##i,##__VA_ARGS__); \ - queue.dispatch(2); \ + queue.call_every(1ms, func##i,##__VA_ARGS__); \ + queue.dispatch_for(2ms); \ TEST_ASSERT(touched); \ } @@ -129,7 +129,7 @@ queue.call_in((i + 1) * 100ms, time_func, &tickers[i], (i + 1) * 100); } - queue.dispatch(N * 100); + queue.dispatch_for(N * 100ms); } template @@ -144,7 +144,7 @@ queue.call_every((i + 1) * 100ms, time_func, &tickers[i], (i + 1) * 100); } - queue.dispatch(N * 100); + queue.dispatch_for(N * 100ms); } void allocate_failure_test() @@ -179,7 +179,7 @@ queue.cancel(ids[i]); } - queue.dispatch(0); + queue.dispatch_once(); } @@ -235,7 +235,7 @@ e1.post(1); e0.post(); - queue.dispatch(0); + queue.dispatch_once(); TEST_ASSERT_EQUAL(counter, 30); } @@ -259,7 +259,7 @@ e1.post(); e0.post(); - queue.dispatch(0); + queue.dispatch_once(); TEST_ASSERT_EQUAL(counter, 15); } @@ -283,7 +283,7 @@ queue.event(callback(count5), 1).post(1, 1, 1, 1); queue.event(callback(count5)).post(1, 1, 1, 1, 1); - queue.dispatch(0); + queue.dispatch_once(); TEST_ASSERT_EQUAL(counter, 60); } @@ -317,7 +317,7 @@ TEST_ASSERT(timeleft_events[0]); TEST_ASSERT(timeleft_events[1]); - queue.dispatch(300); + queue.dispatch_for(300ms); // Ensure check was called TEST_ASSERT(touched); @@ -326,7 +326,7 @@ int id = queue.call(func0); TEST_ASSERT(id); TEST_ASSERT_EQUAL(0, queue.time_left(id)); - queue.dispatch(10); + queue.dispatch_for(10ms); // Test invalid event id TEST_ASSERT_EQUAL(-1, queue.time_left(0)); @@ -418,7 +418,7 @@ ue4.cancel(); e2.cancel(); - queue.dispatch(101); + queue.dispatch_for(101ms); TEST_ASSERT_EQUAL(true, touched); TEST_ASSERT_EQUAL(1, ue1_test.counter); @@ -491,7 +491,7 @@ g_queue.cancel(&ue4); g_queue.cancel(&ue4); - g_queue.dispatch(400); + g_queue.dispatch_for(400ms); TEST_ASSERT_EQUAL(2, test1.counter); TEST_ASSERT_EQUAL(6, test2.counter); @@ -500,7 +500,7 @@ ue4.delay(1); TEST_ASSERT_EQUAL(true, ue4.try_call()); - g_queue.dispatch(1); + g_queue.dispatch_for(1ms); TEST_ASSERT_EQUAL(2, test1.counter); TEST_ASSERT_EQUAL(6, test2.counter); @@ -525,7 +525,7 @@ event1.delay(10ms); event1.period(events::non_periodic); event1.post(); - period_tests_queue.dispatch(80); + period_tests_queue.dispatch_for(80ms); // Wait 100ms and check the event execution status wait_us(100 * 1000); @@ -543,7 +543,7 @@ event2.delay(10ms); event2.period(-10ms); event2.post(); - period_tests_queue.dispatch(80); + period_tests_queue.dispatch_for(80ms); // Wait 100ms and check the event execution status wait_us(100 * 1000); @@ -561,7 +561,7 @@ event3.delay(10ms); event3.period(0ms); event3.post(); - period_tests_queue.dispatch(80); + period_tests_queue.dispatch_for(80ms); // Wait 100ms and check the event execution status wait_us(100 * 1000); @@ -578,7 +578,7 @@ event4.delay(10ms); event4.period(20ms); event4.post(); - period_tests_queue.dispatch(80); + period_tests_queue.dispatch_for(80ms); // Wait 100ms and check the event execution status wait_us(100 * 1000);