This is a fork of the `events` subdirectory of https://github.com/ARMmbed/mbed-os

Dependents:   HelloWorld_CCA01M1 HelloWorld_CCA02M1 CI-data-logger-server HelloWorld_CCA02M1 ... more

This is a fork of the events subdirectory of https://github.com/ARMmbed/mbed-os.

Note, you must import this library with import name: events!!!

Committer:
Kevin Bracey
Date:
Tue May 30 16:12:51 2017 +0300
Revision:
9831:68f03f5d2dd2
Add ability to request a shared event queue

To allow components with a simple need to schedule a few events to not
have to create their own threads, with all the associated memory
overhead, add 2 central calls to get shared normal and an
interrupt-deferral event queues, each dispatched on their own shared
threads.

For non-RTOS systems, just the normal event queue is provided, and the
application would have to dispatch this itself. This
application-dispatch is also available via a config option, to
potentially save memory by reusing the main thread.

Possible future improvement: the ability for separate components to
request a minimum stack size, and have the JSON combine these requests.
(Analogous tooling has already been mooted for mbed TLS config options
like key size).

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kevin Bracey 9831:68f03f5d2dd2 1
Kevin Bracey 9831:68f03f5d2dd2 2 /** \addtogroup events */
Kevin Bracey 9831:68f03f5d2dd2 3 /** @{*/
Kevin Bracey 9831:68f03f5d2dd2 4 /* events
Kevin Bracey 9831:68f03f5d2dd2 5 * Copyright (c) 2017 ARM Limited
Kevin Bracey 9831:68f03f5d2dd2 6 *
Kevin Bracey 9831:68f03f5d2dd2 7 * Licensed under the Apache License, Version 2.0 (the "License");
Kevin Bracey 9831:68f03f5d2dd2 8 * you may not use this file except in compliance with the License.
Kevin Bracey 9831:68f03f5d2dd2 9 * You may obtain a copy of the License at
Kevin Bracey 9831:68f03f5d2dd2 10 *
Kevin Bracey 9831:68f03f5d2dd2 11 * http://www.apache.org/licenses/LICENSE-2.0
Kevin Bracey 9831:68f03f5d2dd2 12 *
Kevin Bracey 9831:68f03f5d2dd2 13 * Unless required by applicable law or agreed to in writing, software
Kevin Bracey 9831:68f03f5d2dd2 14 * distributed under the License is distributed on an "AS IS" BASIS,
Kevin Bracey 9831:68f03f5d2dd2 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Kevin Bracey 9831:68f03f5d2dd2 16 * See the License for the specific language governing permissions and
Kevin Bracey 9831:68f03f5d2dd2 17 * limitations under the License.
Kevin Bracey 9831:68f03f5d2dd2 18 */
Kevin Bracey 9831:68f03f5d2dd2 19 #ifndef MBED_SHARED_QUEUES_H
Kevin Bracey 9831:68f03f5d2dd2 20 #define MBED_SHARED_QUEUES_H
Kevin Bracey 9831:68f03f5d2dd2 21
Kevin Bracey 9831:68f03f5d2dd2 22 #include "events/EventQueue.h"
Kevin Bracey 9831:68f03f5d2dd2 23
Kevin Bracey 9831:68f03f5d2dd2 24 namespace mbed {
Kevin Bracey 9831:68f03f5d2dd2 25
Kevin Bracey 9831:68f03f5d2dd2 26 /**
Kevin Bracey 9831:68f03f5d2dd2 27 * Return a pointer to an EventQueue, on which normal tasks can be queued.
Kevin Bracey 9831:68f03f5d2dd2 28 *
Kevin Bracey 9831:68f03f5d2dd2 29 * All calls to this return the same EventQueue - it and its dispatch thread
Kevin Bracey 9831:68f03f5d2dd2 30 * are created on the first call to this function. The dispatch thread
Kevin Bracey 9831:68f03f5d2dd2 31 * runs at default priority (currently osPriorityNormal).
Kevin Bracey 9831:68f03f5d2dd2 32 *
Kevin Bracey 9831:68f03f5d2dd2 33 * The EventQueue returned may be used to call() Events, or to chain() other
Kevin Bracey 9831:68f03f5d2dd2 34 * EventQueues so that they are run in the same context.
Kevin Bracey 9831:68f03f5d2dd2 35 *
Kevin Bracey 9831:68f03f5d2dd2 36 * Events (or chained EventQueues) executing on the normal event queue should
Kevin Bracey 9831:68f03f5d2dd2 37 * normally take less than 10ms to execute, to avoid starving other users. As
Kevin Bracey 9831:68f03f5d2dd2 38 * such, users can expect that event latency will typically be 10ms or less,
Kevin Bracey 9831:68f03f5d2dd2 39 * but could occasionally be significantly higher if many events are queued.
Kevin Bracey 9831:68f03f5d2dd2 40 *
Kevin Bracey 9831:68f03f5d2dd2 41 * If an RTOS is not present or the configuration option
Kevin Bracey 9831:68f03f5d2dd2 42 * `events.shared-dispatch-from-application` is set to true, then this
Kevin Bracey 9831:68f03f5d2dd2 43 * does not create a dedicated dispatch thread - instead the application is
Kevin Bracey 9831:68f03f5d2dd2 44 * expected to run the EventQueue's dispatch, eg from main. This is necessary
Kevin Bracey 9831:68f03f5d2dd2 45 * for the event loop to work without an RTOS, or an RTOS system can can save
Kevin Bracey 9831:68f03f5d2dd2 46 * memory by reusing the main stack.
Kevin Bracey 9831:68f03f5d2dd2 47 *
Kevin Bracey 9831:68f03f5d2dd2 48 * @return pointer to event queue
Kevin Bracey 9831:68f03f5d2dd2 49 */
Kevin Bracey 9831:68f03f5d2dd2 50 events::EventQueue *mbed_event_queue();
Kevin Bracey 9831:68f03f5d2dd2 51
Kevin Bracey 9831:68f03f5d2dd2 52 #ifdef MBED_CONF_RTOS_PRESENT
Kevin Bracey 9831:68f03f5d2dd2 53 /**
Kevin Bracey 9831:68f03f5d2dd2 54 * Return a pointer to an EventQueue, on which small high-priority tasks can
Kevin Bracey 9831:68f03f5d2dd2 55 * be queues, such as simple deferrals from interrupt.
Kevin Bracey 9831:68f03f5d2dd2 56 *
Kevin Bracey 9831:68f03f5d2dd2 57 * All calls to this return the same EventQueue - it and its thread are
Kevin Bracey 9831:68f03f5d2dd2 58 * created on the first call to this function. The dispatch thread
Kevin Bracey 9831:68f03f5d2dd2 59 * runs at a high priority (currently osPriorityHigh).
Kevin Bracey 9831:68f03f5d2dd2 60 *
Kevin Bracey 9831:68f03f5d2dd2 61 * The EventQueue returned may be used to call() Events, or to chain() other
Kevin Bracey 9831:68f03f5d2dd2 62 * EventQueues so that they are run in the same context.
Kevin Bracey 9831:68f03f5d2dd2 63 *
Kevin Bracey 9831:68f03f5d2dd2 64 * Events (or chained EventQueues) executing on the high-priority event queue
Kevin Bracey 9831:68f03f5d2dd2 65 * should normally take less than 100us to execute, to avoid starving other
Kevin Bracey 9831:68f03f5d2dd2 66 * users. As such, users can expect that event latency will typically be 100us
Kevin Bracey 9831:68f03f5d2dd2 67 * or less, but could occasionally be significantly higher if many events are
Kevin Bracey 9831:68f03f5d2dd2 68 * queued.
Kevin Bracey 9831:68f03f5d2dd2 69 *
Kevin Bracey 9831:68f03f5d2dd2 70 * @return pointer to high-priority event queue
Kevin Bracey 9831:68f03f5d2dd2 71 */
Kevin Bracey 9831:68f03f5d2dd2 72
Kevin Bracey 9831:68f03f5d2dd2 73 events::EventQueue *mbed_highprio_event_queue();
Kevin Bracey 9831:68f03f5d2dd2 74
Kevin Bracey 9831:68f03f5d2dd2 75 #endif // MBED_CONF_RTOS_PRESENT
Kevin Bracey 9831:68f03f5d2dd2 76
Kevin Bracey 9831:68f03f5d2dd2 77 };
Kevin Bracey 9831:68f03f5d2dd2 78
Kevin Bracey 9831:68f03f5d2dd2 79 #endif
Kevin Bracey 9831:68f03f5d2dd2 80
Kevin Bracey 9831:68f03f5d2dd2 81 /** @}*/