erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

events/equeue/equeue.h@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

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