diff --git a/events/README.md b/events/README.md index 9ef90fe3ea9..598748c75a9 100644 --- a/events/README.md +++ b/events/README.md @@ -75,7 +75,7 @@ queue.call_every(400, printf, "called every 0.4 seconds\n"); The call functions return an ID that uniquely represents the event in the the event queue. You can pass this ID to `EventQueue::cancel` to cancel -an in-flight event. +an in-flight event prior to dispatch. ``` cpp // The event id uniquely represents the event in the queue @@ -88,7 +88,7 @@ if (id) { } // Events can be cancelled as long as they have not been dispatched. If the -// event has already expired, cancel has no side-effects. +// event has already expired, cancel may have negative side-effects. queue.cancel(id); ``` @@ -192,7 +192,7 @@ out of interrupt contexts. ## Documentation ## The in-depth documentation on specific functions can be found in -[equeue.h](equeue.h). +[equeue.h](include/events/equeue.h). The core of the equeue library is the `equeue_t` type which represents a single event queue, and the `equeue_dispatch` function which runs the equeue, @@ -257,7 +257,7 @@ int enet_consume(void *buffer, int size) { ``` Additionally, in-flight events can be cancelled with `equeue_cancel`. Events -are given unique ids on post, allowing safe cancellation of expired events. +are given unique ids on post, allowing safe cancellation until dispatch. ``` c #include "equeue.h" diff --git a/events/include/events/Event.h b/events/include/events/Event.h index 6d0fc4019a6..51a543d20fc 100644 --- a/events/include/events/Event.h +++ b/events/include/events/Event.h @@ -228,7 +228,7 @@ class Event { /** Cancels the most recently posted event * - * Attempts to cancel the most recently posted event. It is safe to call + * Attempts to cancel the most recently posted event. It is not safe to call * cancel after an event has already been dispatched. * * The cancel function is IRQ safe. diff --git a/events/include/events/EventQueue.h b/events/include/events/EventQueue.h index 97b898f06f6..a65c8a90682 100644 --- a/events/include/events/EventQueue.h +++ b/events/include/events/EventQueue.h @@ -154,7 +154,7 @@ class EventQueue : private mbed::NonCopyable { /** 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 + * 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. @@ -175,7 +175,7 @@ class EventQueue : private mbed::NonCopyable { /** Cancel an in-flight user allocated event * * Attempts to cancel an UserAllocatedEvent referenced by its address - * It is safe to call cancel after an event has already been dispatched. + * 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. diff --git a/events/include/events/UserAllocatedEvent.h b/events/include/events/UserAllocatedEvent.h index 94dd360b636..27b6aa73161 100644 --- a/events/include/events/UserAllocatedEvent.h +++ b/events/include/events/UserAllocatedEvent.h @@ -230,7 +230,7 @@ class UserAllocatedEvent { /** Cancels posted event * - * Attempts to cancel posted event. It is safe to call + * Attempts to cancel posted event. It is not safe to call * cancel after an event has already been dispatched. * * The cancel function is IRQ safe. diff --git a/events/include/events/equeue.h b/events/include/events/equeue.h index 385f3a52e40..34b56d3b811 100644 --- a/events/include/events/equeue.h +++ b/events/include/events/equeue.h @@ -195,7 +195,7 @@ void equeue_post_user_allocated(equeue_t *queue, void (*cb)(void *), void *event // Cancel an in-flight event // // Attempts to cancel an event referenced by the unique id returned from -// equeue_call or equeue_post. It is safe to call equeue_cancel after an event +// equeue_call or equeue_post. It is not safe to call equeue_cancel after an event // has already been dispatched. // // The equeue_cancel function is irq safe. @@ -210,14 +210,14 @@ bool equeue_cancel(equeue_t *queue, int id); // Cancel an in-flight user allocated event // // Attempts to cancel an event referenced by its address. -// It is safe to call equeue_cancel_user_allocated after an event +// It is not safe to call equeue_cancel_user_allocated after an event // has already been dispatched. // // The equeue_cancel_user_allocated function is irq safe. // // If called while the event queue's dispatch loop is active, // equeue_cancel_user_allocated does not guarantee that the event -// will not not execute after it returns as the event may have +// will not execute after it returns as the event may have // already begun executing. bool equeue_cancel_user_allocated(equeue_t *queue, void *event);