EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

events/equeue/equeue.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

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