ST / ST_Events-old

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!!!

equeue/equeue.h@9832:b95afde9ef7e, 2017-09-05 (annotated)

Committer:
Wolfgang Betz
Date:
Tue Sep 05 09:09:24 2017 +0200
Revision:
9832:b95afde9ef7e
Parent:
5:705843a08e16 
Merge branch 'master' of hg::http://developer.mbed.org/teams/ST/code/ST_Events into events-split

Who changed what in which revision?

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