ON Semiconductor / mbed-os

5.2.1 - Updated I2C files

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

events/equeue/equeue.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

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