Rahul Dahiya / Mbed OS STM32F7 Ethernet

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

mbed-os/events/equeue/equeue.h@0:fb8047b156bb, 2020-01-15 (annotated)

Committer:
rahul_dahiya
Date:
Wed Jan 15 15:57:15 2020 +0530
Revision:
0:fb8047b156bb
STM32F7 LWIP

Who changed what in which revision?

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