Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/events/equeue/equeue.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1
marcozecchini 0:9fca2b23d0ba 2 /** \addtogroup events */
marcozecchini 0:9fca2b23d0ba 3 /** @{*/
marcozecchini 0:9fca2b23d0ba 4 /*
marcozecchini 0:9fca2b23d0ba 5 * Flexible event queue for dispatching events
marcozecchini 0:9fca2b23d0ba 6 *
marcozecchini 0:9fca2b23d0ba 7 * Copyright (c) 2016 Christopher Haster
marcozecchini 0:9fca2b23d0ba 8 *
marcozecchini 0:9fca2b23d0ba 9 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 10 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 11 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 12 *
marcozecchini 0:9fca2b23d0ba 13 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 14 *
marcozecchini 0:9fca2b23d0ba 15 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 16 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 18 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 19 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 20 */
marcozecchini 0:9fca2b23d0ba 21 #ifndef EQUEUE_H
marcozecchini 0:9fca2b23d0ba 22 #define EQUEUE_H
marcozecchini 0:9fca2b23d0ba 23
marcozecchini 0:9fca2b23d0ba 24 #ifdef __cplusplus
marcozecchini 0:9fca2b23d0ba 25 extern "C" {
marcozecchini 0:9fca2b23d0ba 26 #endif
marcozecchini 0:9fca2b23d0ba 27
marcozecchini 0:9fca2b23d0ba 28 // Platform specific files
marcozecchini 0:9fca2b23d0ba 29 #include "equeue/equeue_platform.h"
marcozecchini 0:9fca2b23d0ba 30
marcozecchini 0:9fca2b23d0ba 31 #include <stddef.h>
marcozecchini 0:9fca2b23d0ba 32 #include <stdint.h>
marcozecchini 0:9fca2b23d0ba 33
marcozecchini 0:9fca2b23d0ba 34
marcozecchini 0:9fca2b23d0ba 35 // The minimum size of an event
marcozecchini 0:9fca2b23d0ba 36 // This size is guaranteed to fit events created by event_call
marcozecchini 0:9fca2b23d0ba 37 #define EQUEUE_EVENT_SIZE (sizeof(struct equeue_event) + 2*sizeof(void*))
marcozecchini 0:9fca2b23d0ba 38
marcozecchini 0:9fca2b23d0ba 39 // Internal event structure
marcozecchini 0:9fca2b23d0ba 40 struct equeue_event {
marcozecchini 0:9fca2b23d0ba 41 unsigned size;
marcozecchini 0:9fca2b23d0ba 42 uint8_t id;
marcozecchini 0:9fca2b23d0ba 43 uint8_t generation;
marcozecchini 0:9fca2b23d0ba 44
marcozecchini 0:9fca2b23d0ba 45 struct equeue_event *next;
marcozecchini 0:9fca2b23d0ba 46 struct equeue_event *sibling;
marcozecchini 0:9fca2b23d0ba 47 struct equeue_event **ref;
marcozecchini 0:9fca2b23d0ba 48
marcozecchini 0:9fca2b23d0ba 49 unsigned target;
marcozecchini 0:9fca2b23d0ba 50 int period;
marcozecchini 0:9fca2b23d0ba 51 void (*dtor)(void *);
marcozecchini 0:9fca2b23d0ba 52
marcozecchini 0:9fca2b23d0ba 53 void (*cb)(void *);
marcozecchini 0:9fca2b23d0ba 54 // data follows
marcozecchini 0:9fca2b23d0ba 55 };
marcozecchini 0:9fca2b23d0ba 56
marcozecchini 0:9fca2b23d0ba 57 // Event queue structure
marcozecchini 0:9fca2b23d0ba 58 typedef struct equeue {
marcozecchini 0:9fca2b23d0ba 59 struct equeue_event *queue;
marcozecchini 0:9fca2b23d0ba 60 unsigned tick;
marcozecchini 0:9fca2b23d0ba 61 unsigned breaks;
marcozecchini 0:9fca2b23d0ba 62 uint8_t generation;
marcozecchini 0:9fca2b23d0ba 63
marcozecchini 0:9fca2b23d0ba 64 unsigned char *buffer;
marcozecchini 0:9fca2b23d0ba 65 unsigned npw2;
marcozecchini 0:9fca2b23d0ba 66 void *allocated;
marcozecchini 0:9fca2b23d0ba 67
marcozecchini 0:9fca2b23d0ba 68 struct equeue_event *chunks;
marcozecchini 0:9fca2b23d0ba 69 struct equeue_slab {
marcozecchini 0:9fca2b23d0ba 70 size_t size;
marcozecchini 0:9fca2b23d0ba 71 unsigned char *data;
marcozecchini 0:9fca2b23d0ba 72 } slab;
marcozecchini 0:9fca2b23d0ba 73
marcozecchini 0:9fca2b23d0ba 74 struct equeue_background {
marcozecchini 0:9fca2b23d0ba 75 bool active;
marcozecchini 0:9fca2b23d0ba 76 void (*update)(void *timer, int ms);
marcozecchini 0:9fca2b23d0ba 77 void *timer;
marcozecchini 0:9fca2b23d0ba 78 } background;
marcozecchini 0:9fca2b23d0ba 79
marcozecchini 0:9fca2b23d0ba 80 equeue_sema_t eventsema;
marcozecchini 0:9fca2b23d0ba 81 equeue_mutex_t queuelock;
marcozecchini 0:9fca2b23d0ba 82 equeue_mutex_t memlock;
marcozecchini 0:9fca2b23d0ba 83 } equeue_t;
marcozecchini 0:9fca2b23d0ba 84
marcozecchini 0:9fca2b23d0ba 85
marcozecchini 0:9fca2b23d0ba 86 // Queue lifetime operations
marcozecchini 0:9fca2b23d0ba 87 //
marcozecchini 0:9fca2b23d0ba 88 // Creates and destroys an event queue. The event queue either allocates a
marcozecchini 0:9fca2b23d0ba 89 // buffer of the specified size with malloc or uses a user provided buffer
marcozecchini 0:9fca2b23d0ba 90 // if constructed with equeue_create_inplace.
marcozecchini 0:9fca2b23d0ba 91 //
marcozecchini 0:9fca2b23d0ba 92 // If the event queue creation fails, equeue_create returns a negative,
marcozecchini 0:9fca2b23d0ba 93 // platform-specific error code.
marcozecchini 0:9fca2b23d0ba 94 int equeue_create(equeue_t *queue, size_t size);
marcozecchini 0:9fca2b23d0ba 95 int equeue_create_inplace(equeue_t *queue, size_t size, void *buffer);
marcozecchini 0:9fca2b23d0ba 96 void equeue_destroy(equeue_t *queue);
marcozecchini 0:9fca2b23d0ba 97
marcozecchini 0:9fca2b23d0ba 98 // Dispatch events
marcozecchini 0:9fca2b23d0ba 99 //
marcozecchini 0:9fca2b23d0ba 100 // Executes events until the specified milliseconds have passed. If ms is
marcozecchini 0:9fca2b23d0ba 101 // negative, equeue_dispatch will dispatch events indefinitely or until
marcozecchini 0:9fca2b23d0ba 102 // equeue_break is called on this queue.
marcozecchini 0:9fca2b23d0ba 103 //
marcozecchini 0:9fca2b23d0ba 104 // When called with a finite timeout, the equeue_dispatch function is
marcozecchini 0:9fca2b23d0ba 105 // guaranteed to terminate. When called with a timeout of 0, the
marcozecchini 0:9fca2b23d0ba 106 // equeue_dispatch does not wait and is irq safe.
marcozecchini 0:9fca2b23d0ba 107 void equeue_dispatch(equeue_t *queue, int ms);
marcozecchini 0:9fca2b23d0ba 108
marcozecchini 0:9fca2b23d0ba 109 // Break out of a running event loop
marcozecchini 0:9fca2b23d0ba 110 //
marcozecchini 0:9fca2b23d0ba 111 // Forces the specified event queue's dispatch loop to terminate. Pending
marcozecchini 0:9fca2b23d0ba 112 // events may finish executing, but no new events will be executed.
marcozecchini 0:9fca2b23d0ba 113 void equeue_break(equeue_t *queue);
marcozecchini 0:9fca2b23d0ba 114
marcozecchini 0:9fca2b23d0ba 115 // Simple event calls
marcozecchini 0:9fca2b23d0ba 116 //
marcozecchini 0:9fca2b23d0ba 117 // The specified callback will be executed in the context of the event queue's
marcozecchini 0:9fca2b23d0ba 118 // dispatch loop. When the callback is executed depends on the call function.
marcozecchini 0:9fca2b23d0ba 119 //
marcozecchini 0:9fca2b23d0ba 120 // equeue_call - Immediately post an event to the queue
marcozecchini 0:9fca2b23d0ba 121 // equeue_call_in - Post an event after a specified time in milliseconds
marcozecchini 0:9fca2b23d0ba 122 // equeue_call_every - Post an event periodically every milliseconds
marcozecchini 0:9fca2b23d0ba 123 //
marcozecchini 0:9fca2b23d0ba 124 // All equeue_call functions are irq safe and can act as a mechanism for
marcozecchini 0:9fca2b23d0ba 125 // moving events out of irq contexts.
marcozecchini 0:9fca2b23d0ba 126 //
marcozecchini 0:9fca2b23d0ba 127 // The return value is a unique id that represents the posted event and can
marcozecchini 0:9fca2b23d0ba 128 // be passed to equeue_cancel. If there is not enough memory to allocate the
marcozecchini 0:9fca2b23d0ba 129 // event, equeue_call returns an id of 0.
marcozecchini 0:9fca2b23d0ba 130 int equeue_call(equeue_t *queue, void (*cb)(void *), void *data);
marcozecchini 0:9fca2b23d0ba 131 int equeue_call_in(equeue_t *queue, int ms, void (*cb)(void *), void *data);
marcozecchini 0:9fca2b23d0ba 132 int equeue_call_every(equeue_t *queue, int ms, void (*cb)(void *), void *data);
marcozecchini 0:9fca2b23d0ba 133
marcozecchini 0:9fca2b23d0ba 134 // Allocate memory for events
marcozecchini 0:9fca2b23d0ba 135 //
marcozecchini 0:9fca2b23d0ba 136 // The equeue_alloc function allocates an event that can be manually dispatched
marcozecchini 0:9fca2b23d0ba 137 // with equeue_post. The equeue_dealloc function may be used to free an event
marcozecchini 0:9fca2b23d0ba 138 // that has not been posted. Once posted, an event's memory is managed by the
marcozecchini 0:9fca2b23d0ba 139 // event queue and should not be deallocated.
marcozecchini 0:9fca2b23d0ba 140 //
marcozecchini 0:9fca2b23d0ba 141 // Both equeue_alloc and equeue_dealloc are irq safe.
marcozecchini 0:9fca2b23d0ba 142 //
marcozecchini 0:9fca2b23d0ba 143 // The equeue allocator is designed to minimize jitter in interrupt contexts as
marcozecchini 0:9fca2b23d0ba 144 // well as avoid memory fragmentation on small devices. The allocator achieves
marcozecchini 0:9fca2b23d0ba 145 // both constant-runtime and zero-fragmentation for fixed-size events, however
marcozecchini 0:9fca2b23d0ba 146 // grows linearly as the quantity of different sized allocations increases.
marcozecchini 0:9fca2b23d0ba 147 //
marcozecchini 0:9fca2b23d0ba 148 // The equeue_alloc function returns a pointer to the event's allocated memory
marcozecchini 0:9fca2b23d0ba 149 // and acts as a handle to the underlying event. If there is not enough memory
marcozecchini 0:9fca2b23d0ba 150 // to allocate the event, equeue_alloc returns null.
marcozecchini 0:9fca2b23d0ba 151 void *equeue_alloc(equeue_t *queue, size_t size);
marcozecchini 0:9fca2b23d0ba 152 void equeue_dealloc(equeue_t *queue, void *event);
marcozecchini 0:9fca2b23d0ba 153
marcozecchini 0:9fca2b23d0ba 154 // Configure an allocated event
marcozecchini 0:9fca2b23d0ba 155 //
marcozecchini 0:9fca2b23d0ba 156 // equeue_event_delay - Millisecond delay before dispatching an event
marcozecchini 0:9fca2b23d0ba 157 // equeue_event_period - Millisecond period for repeating dispatching an event
marcozecchini 0:9fca2b23d0ba 158 // equeue_event_dtor - Destructor to run when the event is deallocated
marcozecchini 0:9fca2b23d0ba 159 void equeue_event_delay(void *event, int ms);
marcozecchini 0:9fca2b23d0ba 160 void equeue_event_period(void *event, int ms);
marcozecchini 0:9fca2b23d0ba 161 void equeue_event_dtor(void *event, void (*dtor)(void *));
marcozecchini 0:9fca2b23d0ba 162
marcozecchini 0:9fca2b23d0ba 163 // Post an event onto the event queue
marcozecchini 0:9fca2b23d0ba 164 //
marcozecchini 0:9fca2b23d0ba 165 // The equeue_post function takes a callback and a pointer to an event
marcozecchini 0:9fca2b23d0ba 166 // allocated by equeue_alloc. The specified callback will be executed in the
marcozecchini 0:9fca2b23d0ba 167 // context of the event queue's dispatch loop with the allocated event
marcozecchini 0:9fca2b23d0ba 168 // as its argument.
marcozecchini 0:9fca2b23d0ba 169 //
marcozecchini 0:9fca2b23d0ba 170 // The equeue_post function is irq safe and can act as a mechanism for
marcozecchini 0:9fca2b23d0ba 171 // moving events out of irq contexts.
marcozecchini 0:9fca2b23d0ba 172 //
marcozecchini 0:9fca2b23d0ba 173 // The return value is a unique id that represents the posted event and can
marcozecchini 0:9fca2b23d0ba 174 // be passed to equeue_cancel.
marcozecchini 0:9fca2b23d0ba 175 int equeue_post(equeue_t *queue, void (*cb)(void *), void *event);
marcozecchini 0:9fca2b23d0ba 176
marcozecchini 0:9fca2b23d0ba 177 // Cancel an in-flight event
marcozecchini 0:9fca2b23d0ba 178 //
marcozecchini 0:9fca2b23d0ba 179 // Attempts to cancel an event referenced by the unique id returned from
marcozecchini 0:9fca2b23d0ba 180 // equeue_call or equeue_post. It is safe to call equeue_cancel after an event
marcozecchini 0:9fca2b23d0ba 181 // has already been dispatched.
marcozecchini 0:9fca2b23d0ba 182 //
marcozecchini 0:9fca2b23d0ba 183 // The equeue_cancel function is irq safe.
marcozecchini 0:9fca2b23d0ba 184 //
marcozecchini 0:9fca2b23d0ba 185 // If called while the event queue's dispatch loop is active, equeue_cancel
marcozecchini 0:9fca2b23d0ba 186 // does not guarantee that the event will not not execute after it returns as
marcozecchini 0:9fca2b23d0ba 187 // the event may have already begun executing.
marcozecchini 0:9fca2b23d0ba 188 void equeue_cancel(equeue_t *queue, int id);
marcozecchini 0:9fca2b23d0ba 189
marcozecchini 0:9fca2b23d0ba 190 // Background an event queue onto a single-shot timer
marcozecchini 0:9fca2b23d0ba 191 //
marcozecchini 0:9fca2b23d0ba 192 // The provided update function will be called to indicate when the queue
marcozecchini 0:9fca2b23d0ba 193 // should be dispatched. A negative timeout will be passed to the update
marcozecchini 0:9fca2b23d0ba 194 // function when the timer is no longer needed.
marcozecchini 0:9fca2b23d0ba 195 //
marcozecchini 0:9fca2b23d0ba 196 // Passing a null update function disables the existing timer.
marcozecchini 0:9fca2b23d0ba 197 //
marcozecchini 0:9fca2b23d0ba 198 // The equeue_background function allows an event queue to take advantage
marcozecchini 0:9fca2b23d0ba 199 // of hardware timers or even other event loops, allowing an event queue to
marcozecchini 0:9fca2b23d0ba 200 // be effectively backgrounded.
marcozecchini 0:9fca2b23d0ba 201 void equeue_background(equeue_t *queue,
marcozecchini 0:9fca2b23d0ba 202 void (*update)(void *timer, int ms), void *timer);
marcozecchini 0:9fca2b23d0ba 203
marcozecchini 0:9fca2b23d0ba 204 // Chain an event queue onto another event queue
marcozecchini 0:9fca2b23d0ba 205 //
marcozecchini 0:9fca2b23d0ba 206 // After chaining a queue to a target, calling equeue_dispatch on the
marcozecchini 0:9fca2b23d0ba 207 // target queue will also dispatch events from this queue. The queues
marcozecchini 0:9fca2b23d0ba 208 // use their own buffers and events must be managed independently.
marcozecchini 0:9fca2b23d0ba 209 //
marcozecchini 0:9fca2b23d0ba 210 // Passing a null queue as the target will unchain the existing queue.
marcozecchini 0:9fca2b23d0ba 211 //
marcozecchini 0:9fca2b23d0ba 212 // The equeue_chain function allows multiple equeues to be composed, sharing
marcozecchini 0:9fca2b23d0ba 213 // the context of a dispatch loop while still being managed independently.
marcozecchini 0:9fca2b23d0ba 214 void equeue_chain(equeue_t *queue, equeue_t *target);
marcozecchini 0:9fca2b23d0ba 215
marcozecchini 0:9fca2b23d0ba 216
marcozecchini 0:9fca2b23d0ba 217 #ifdef __cplusplus
marcozecchini 0:9fca2b23d0ba 218 }
marcozecchini 0:9fca2b23d0ba 219 #endif
marcozecchini 0:9fca2b23d0ba 220
marcozecchini 0:9fca2b23d0ba 221 #endif
marcozecchini 0:9fca2b23d0ba 222
marcozecchini 0:9fca2b23d0ba 223 /** @}*/