Marco Zecchini
/
Example_RTOS
Rtos API example
Embed:
(wiki syntax)
Show/hide line numbers
equeue.h
00001 00002 /** \addtogroup events */ 00003 /** @{*/ 00004 /* 00005 * Flexible event queue for dispatching events 00006 * 00007 * Copyright (c) 2016 Christopher Haster 00008 * 00009 * Licensed under the Apache License, Version 2.0 (the "License"); 00010 * you may not use this file except in compliance with the License. 00011 * You may obtain a copy of the License at 00012 * 00013 * http://www.apache.org/licenses/LICENSE-2.0 00014 * 00015 * Unless required by applicable law or agreed to in writing, software 00016 * distributed under the License is distributed on an "AS IS" BASIS, 00017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00018 * See the License for the specific language governing permissions and 00019 * limitations under the License. 00020 */ 00021 #ifndef EQUEUE_H 00022 #define EQUEUE_H 00023 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 // Platform specific files 00029 #include "equeue/equeue_platform.h" 00030 00031 #include <stddef.h> 00032 #include <stdint.h> 00033 00034 00035 // The minimum size of an event 00036 // This size is guaranteed to fit events created by event_call 00037 #define EQUEUE_EVENT_SIZE (sizeof(struct equeue_event) + 2*sizeof(void*)) 00038 00039 // Internal event structure 00040 struct equeue_event { 00041 unsigned size; 00042 uint8_t id; 00043 uint8_t generation; 00044 00045 struct equeue_event *next; 00046 struct equeue_event *sibling; 00047 struct equeue_event **ref; 00048 00049 unsigned target; 00050 int period; 00051 void (*dtor)(void *); 00052 00053 void (*cb)(void *); 00054 // data follows 00055 }; 00056 00057 // Event queue structure 00058 typedef struct equeue { 00059 struct equeue_event *queue; 00060 unsigned tick; 00061 unsigned breaks; 00062 uint8_t generation; 00063 00064 unsigned char *buffer; 00065 unsigned npw2; 00066 void *allocated; 00067 00068 struct equeue_event *chunks; 00069 struct equeue_slab { 00070 size_t size; 00071 unsigned char *data; 00072 } slab; 00073 00074 struct equeue_background { 00075 bool active; 00076 void (*update)(void *timer, int ms); 00077 void *timer; 00078 } background; 00079 00080 equeue_sema_t eventsema; 00081 equeue_mutex_t queuelock; 00082 equeue_mutex_t memlock; 00083 } equeue_t; 00084 00085 00086 // Queue lifetime operations 00087 // 00088 // Creates and destroys an event queue. The event queue either allocates a 00089 // buffer of the specified size with malloc or uses a user provided buffer 00090 // if constructed with equeue_create_inplace. 00091 // 00092 // If the event queue creation fails, equeue_create returns a negative, 00093 // platform-specific error code. 00094 int equeue_create(equeue_t *queue, size_t size); 00095 int equeue_create_inplace(equeue_t *queue, size_t size, void *buffer); 00096 void equeue_destroy(equeue_t *queue); 00097 00098 // Dispatch events 00099 // 00100 // Executes events until the specified milliseconds have passed. If ms is 00101 // negative, equeue_dispatch will dispatch events indefinitely or until 00102 // equeue_break is called on this queue. 00103 // 00104 // When called with a finite timeout, the equeue_dispatch function is 00105 // guaranteed to terminate. When called with a timeout of 0, the 00106 // equeue_dispatch does not wait and is irq safe. 00107 void equeue_dispatch(equeue_t *queue, int ms); 00108 00109 // Break out of a running event loop 00110 // 00111 // Forces the specified event queue's dispatch loop to terminate. Pending 00112 // events may finish executing, but no new events will be executed. 00113 void equeue_break(equeue_t *queue); 00114 00115 // Simple event calls 00116 // 00117 // The specified callback will be executed in the context of the event queue's 00118 // dispatch loop. When the callback is executed depends on the call function. 00119 // 00120 // equeue_call - Immediately post an event to the queue 00121 // equeue_call_in - Post an event after a specified time in milliseconds 00122 // equeue_call_every - Post an event periodically every milliseconds 00123 // 00124 // All equeue_call functions are irq safe and can act as a mechanism for 00125 // moving events out of irq contexts. 00126 // 00127 // The return value is a unique id that represents the posted event and can 00128 // be passed to equeue_cancel. If there is not enough memory to allocate the 00129 // event, equeue_call returns an id of 0. 00130 int equeue_call(equeue_t *queue, void (*cb)(void *), void *data); 00131 int equeue_call_in(equeue_t *queue, int ms, void (*cb)(void *), void *data); 00132 int equeue_call_every(equeue_t *queue, int ms, void (*cb)(void *), void *data); 00133 00134 // Allocate memory for events 00135 // 00136 // The equeue_alloc function allocates an event that can be manually dispatched 00137 // with equeue_post. The equeue_dealloc function may be used to free an event 00138 // that has not been posted. Once posted, an event's memory is managed by the 00139 // event queue and should not be deallocated. 00140 // 00141 // Both equeue_alloc and equeue_dealloc are irq safe. 00142 // 00143 // The equeue allocator is designed to minimize jitter in interrupt contexts as 00144 // well as avoid memory fragmentation on small devices. The allocator achieves 00145 // both constant-runtime and zero-fragmentation for fixed-size events, however 00146 // grows linearly as the quantity of different sized allocations increases. 00147 // 00148 // The equeue_alloc function returns a pointer to the event's allocated memory 00149 // and acts as a handle to the underlying event. If there is not enough memory 00150 // to allocate the event, equeue_alloc returns null. 00151 void *equeue_alloc(equeue_t *queue, size_t size); 00152 void equeue_dealloc(equeue_t *queue, void *event); 00153 00154 // Configure an allocated event 00155 // 00156 // equeue_event_delay - Millisecond delay before dispatching an event 00157 // equeue_event_period - Millisecond period for repeating dispatching an event 00158 // equeue_event_dtor - Destructor to run when the event is deallocated 00159 void equeue_event_delay(void *event, int ms); 00160 void equeue_event_period(void *event, int ms); 00161 void equeue_event_dtor(void *event, void (*dtor)(void *)); 00162 00163 // Post an event onto the event queue 00164 // 00165 // The equeue_post function takes a callback and a pointer to an event 00166 // allocated by equeue_alloc. The specified callback will be executed in the 00167 // context of the event queue's dispatch loop with the allocated event 00168 // as its argument. 00169 // 00170 // The equeue_post function is irq safe and can act as a mechanism for 00171 // moving events out of irq contexts. 00172 // 00173 // The return value is a unique id that represents the posted event and can 00174 // be passed to equeue_cancel. 00175 int equeue_post(equeue_t *queue, void (*cb)(void *), void *event); 00176 00177 // Cancel an in-flight event 00178 // 00179 // Attempts to cancel an event referenced by the unique id returned from 00180 // equeue_call or equeue_post. It is safe to call equeue_cancel after an event 00181 // has already been dispatched. 00182 // 00183 // The equeue_cancel function is irq safe. 00184 // 00185 // If called while the event queue's dispatch loop is active, equeue_cancel 00186 // does not guarantee that the event will not not execute after it returns as 00187 // the event may have already begun executing. 00188 void equeue_cancel(equeue_t *queue, int id); 00189 00190 // Background an event queue onto a single-shot timer 00191 // 00192 // The provided update function will be called to indicate when the queue 00193 // should be dispatched. A negative timeout will be passed to the update 00194 // function when the timer is no longer needed. 00195 // 00196 // Passing a null update function disables the existing timer. 00197 // 00198 // The equeue_background function allows an event queue to take advantage 00199 // of hardware timers or even other event loops, allowing an event queue to 00200 // be effectively backgrounded. 00201 void equeue_background(equeue_t *queue, 00202 void (*update)(void *timer, int ms), void *timer); 00203 00204 // Chain an event queue onto another event queue 00205 // 00206 // After chaining a queue to a target, calling equeue_dispatch on the 00207 // target queue will also dispatch events from this queue. The queues 00208 // use their own buffers and events must be managed independently. 00209 // 00210 // Passing a null queue as the target will unchain the existing queue. 00211 // 00212 // The equeue_chain function allows multiple equeues to be composed, sharing 00213 // the context of a dispatch loop while still being managed independently. 00214 void equeue_chain(equeue_t *queue, equeue_t *target); 00215 00216 00217 #ifdef __cplusplus 00218 } 00219 #endif 00220 00221 #endif 00222 00223 /** @}*/
Generated on Sun Jul 17 2022 08:25:22 by 1.7.2