leo hendrickson / Mbed OS S

simple-mbed-cloud-client/mbed-cloud-client/sal-stack-nanostack-eventloop/nanostack-event-loop/eventOS_event.h@0:25fa8795676b, 2021-04-18 (annotated)

Committer:
leothedragon
Date:
Sun Apr 18 15:20:23 2021 +0000
Revision:
0:25fa8795676b
DS

Who changed what in which revision?

UserRevisionLine numberNew contents of line
leothedragon 0:25fa8795676b 1 /*
leothedragon 0:25fa8795676b 2 * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
leothedragon 0:25fa8795676b 3 * SPDX-License-Identifier: Apache-2.0
leothedragon 0:25fa8795676b 4 * Licensed under the Apache License, Version 2.0 (the License); you may
leothedragon 0:25fa8795676b 5 * not use this file except in compliance with the License.
leothedragon 0:25fa8795676b 6 * You may obtain a copy of the License at
leothedragon 0:25fa8795676b 7 *
leothedragon 0:25fa8795676b 8 * http://www.apache.org/licenses/LICENSE-2.0
leothedragon 0:25fa8795676b 9 *
leothedragon 0:25fa8795676b 10 * Unless required by applicable law or agreed to in writing, software
leothedragon 0:25fa8795676b 11 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
leothedragon 0:25fa8795676b 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
leothedragon 0:25fa8795676b 13 * See the License for the specific language governing permissions and
leothedragon 0:25fa8795676b 14 * limitations under the License.
leothedragon 0:25fa8795676b 15 */
leothedragon 0:25fa8795676b 16 #ifndef EVENTOS_EVENT_H_
leothedragon 0:25fa8795676b 17 #define EVENTOS_EVENT_H_
leothedragon 0:25fa8795676b 18 #ifdef __cplusplus
leothedragon 0:25fa8795676b 19 extern "C" {
leothedragon 0:25fa8795676b 20 #endif
leothedragon 0:25fa8795676b 21
leothedragon 0:25fa8795676b 22 #include "ns_types.h"
leothedragon 0:25fa8795676b 23 #include "ns_list.h"
leothedragon 0:25fa8795676b 24
leothedragon 0:25fa8795676b 25 /**
leothedragon 0:25fa8795676b 26 * \enum arm_library_event_priority_e
leothedragon 0:25fa8795676b 27 * \brief Event Priority level.
leothedragon 0:25fa8795676b 28 */
leothedragon 0:25fa8795676b 29 typedef enum arm_library_event_priority_e {
leothedragon 0:25fa8795676b 30 ARM_LIB_HIGH_PRIORITY_EVENT = 0, /**< High Priority Event (Function CB) */
leothedragon 0:25fa8795676b 31 ARM_LIB_MED_PRIORITY_EVENT = 1, /**< Medium Priority (Timer) */
leothedragon 0:25fa8795676b 32 ARM_LIB_LOW_PRIORITY_EVENT = 2, /*!*< Normal Event and ECC / Security */
leothedragon 0:25fa8795676b 33 } arm_library_event_priority_e;
leothedragon 0:25fa8795676b 34
leothedragon 0:25fa8795676b 35 /**
leothedragon 0:25fa8795676b 36 * \struct arm_event_s
leothedragon 0:25fa8795676b 37 * \brief Event structure.
leothedragon 0:25fa8795676b 38 */
leothedragon 0:25fa8795676b 39 typedef struct arm_event_s {
leothedragon 0:25fa8795676b 40 int8_t receiver; /**< Event handler Tasklet ID */
leothedragon 0:25fa8795676b 41 int8_t sender; /**< Event sender Tasklet ID */
leothedragon 0:25fa8795676b 42 uint8_t event_type; /**< This will be typecast arm_library_event_type_e, arm_internal_event_type_e or application specific define */
leothedragon 0:25fa8795676b 43 uint8_t event_id; /**< Timer ID, NWK interface ID or application specific ID */
leothedragon 0:25fa8795676b 44 void *data_ptr; /**< Application could share data pointer tasklet to tasklet */
leothedragon 0:25fa8795676b 45 arm_library_event_priority_e priority;
leothedragon 0:25fa8795676b 46 uint32_t event_data;
leothedragon 0:25fa8795676b 47 } arm_event_t;
leothedragon 0:25fa8795676b 48
leothedragon 0:25fa8795676b 49 /* Backwards compatibility */
leothedragon 0:25fa8795676b 50 typedef arm_event_t arm_event_s;
leothedragon 0:25fa8795676b 51
leothedragon 0:25fa8795676b 52 /**
leothedragon 0:25fa8795676b 53 * \struct arm_event_storage
leothedragon 0:25fa8795676b 54 * \brief Event structure storage, including list link.
leothedragon 0:25fa8795676b 55
leothedragon 0:25fa8795676b 56 @startuml
leothedragon 0:25fa8795676b 57
leothedragon 0:25fa8795676b 58 partition "Event loop" {
leothedragon 0:25fa8795676b 59 (*) -->[event created] "UNQUEUED"
leothedragon 0:25fa8795676b 60 "UNQUEUED" -->[event_core_write()] "QUEUED"
leothedragon 0:25fa8795676b 61 "QUEUED" -->[event_core_read()] "RUNNING"
leothedragon 0:25fa8795676b 62 "RUNNING" ->[event_core_free_push()] "UNQUEUED"
leothedragon 0:25fa8795676b 63 }
leothedragon 0:25fa8795676b 64
leothedragon 0:25fa8795676b 65 partition "system_timer.c" {
leothedragon 0:25fa8795676b 66 "UNQUEUED:timer" -->[eventOS_event_send_timer_allocated()] "QUEUED"
leothedragon 0:25fa8795676b 67 }
leothedragon 0:25fa8795676b 68 @enduml
leothedragon 0:25fa8795676b 69
leothedragon 0:25fa8795676b 70 */
leothedragon 0:25fa8795676b 71 typedef struct arm_event_storage {
leothedragon 0:25fa8795676b 72 arm_event_s data;
leothedragon 0:25fa8795676b 73 enum {
leothedragon 0:25fa8795676b 74 ARM_LIB_EVENT_STARTUP_POOL,
leothedragon 0:25fa8795676b 75 ARM_LIB_EVENT_DYNAMIC,
leothedragon 0:25fa8795676b 76 ARM_LIB_EVENT_USER,
leothedragon 0:25fa8795676b 77 ARM_LIB_EVENT_TIMER,
leothedragon 0:25fa8795676b 78 } allocator;
leothedragon 0:25fa8795676b 79 enum {
leothedragon 0:25fa8795676b 80 ARM_LIB_EVENT_UNQUEUED,
leothedragon 0:25fa8795676b 81 ARM_LIB_EVENT_QUEUED,
leothedragon 0:25fa8795676b 82 ARM_LIB_EVENT_RUNNING,
leothedragon 0:25fa8795676b 83 } state;
leothedragon 0:25fa8795676b 84 ns_list_link_t link;
leothedragon 0:25fa8795676b 85 } arm_event_storage_t;
leothedragon 0:25fa8795676b 86
leothedragon 0:25fa8795676b 87 /**
leothedragon 0:25fa8795676b 88 * \brief Send event to event scheduler.
leothedragon 0:25fa8795676b 89 *
leothedragon 0:25fa8795676b 90 * \param event pointer to pushed event.
leothedragon 0:25fa8795676b 91 *
leothedragon 0:25fa8795676b 92 * Event data is copied by the call, and this copy persists until the
leothedragon 0:25fa8795676b 93 * recipient's callback function returns. The callback function is passed
leothedragon 0:25fa8795676b 94 * a pointer to a copy of the data, not the original pointer.
leothedragon 0:25fa8795676b 95 *
leothedragon 0:25fa8795676b 96 * \return 0 Event push OK
leothedragon 0:25fa8795676b 97 * \return -1 Memory allocation Fail
leothedragon 0:25fa8795676b 98 */
leothedragon 0:25fa8795676b 99 extern int8_t eventOS_event_send(const arm_event_t *event);
leothedragon 0:25fa8795676b 100
leothedragon 0:25fa8795676b 101 /* Alternate names for timer function from eventOS_event_timer.h;
leothedragon 0:25fa8795676b 102 * implementations may one day merge */
leothedragon 0:25fa8795676b 103 #define eventOS_event_send_at(event, at) eventOS_event_timer_request_at(event, at)
leothedragon 0:25fa8795676b 104 #define eventOS_event_send_in(event, in) eventOS_event_timer_request_in(event, in)
leothedragon 0:25fa8795676b 105 #define eventOS_event_send_after(event, after) eventOS_event_timer_request_after(event, after)
leothedragon 0:25fa8795676b 106 #define eventOS_event_send_every(event, every) eventOS_event_timer_request_every(event, every)
leothedragon 0:25fa8795676b 107
leothedragon 0:25fa8795676b 108 /**
leothedragon 0:25fa8795676b 109 * \brief Send user-allocated event to event scheduler.
leothedragon 0:25fa8795676b 110 *
leothedragon 0:25fa8795676b 111 * \param event pointer to pushed event storage.
leothedragon 0:25fa8795676b 112 *
leothedragon 0:25fa8795676b 113 * The event structure is not copied by the call, the event system takes
leothedragon 0:25fa8795676b 114 * ownership and it is threaded directly into the event queue. This avoids the
leothedragon 0:25fa8795676b 115 * possibility of event sending failing due to memory exhaustion.
leothedragon 0:25fa8795676b 116 *
leothedragon 0:25fa8795676b 117 * event->data must be filled in on entry - the rest of the structure (link and
leothedragon 0:25fa8795676b 118 * allocator) need not be.
leothedragon 0:25fa8795676b 119 *
leothedragon 0:25fa8795676b 120 * The structure must remain valid until the recipient is called - the
leothedragon 0:25fa8795676b 121 * event system passes ownership to the receiving event handler, who may then
leothedragon 0:25fa8795676b 122 * invalidate it, or send it again.
leothedragon 0:25fa8795676b 123 *
leothedragon 0:25fa8795676b 124 * The recipient receives a pointer to the arm_event_t data member of the
leothedragon 0:25fa8795676b 125 * event - it can use NS_CONTAINER_OF() to get a pointer to the original
leothedragon 0:25fa8795676b 126 * event passed to this call, or to its outer container.
leothedragon 0:25fa8795676b 127 *
leothedragon 0:25fa8795676b 128 * It is a program error to send a user-allocated event to a non-existent task.
leothedragon 0:25fa8795676b 129 */
leothedragon 0:25fa8795676b 130 extern void eventOS_event_send_user_allocated(arm_event_storage_t *event);
leothedragon 0:25fa8795676b 131
leothedragon 0:25fa8795676b 132 /**
leothedragon 0:25fa8795676b 133 * \brief Event handler callback register
leothedragon 0:25fa8795676b 134 *
leothedragon 0:25fa8795676b 135 * Function will register and allocate unique event id handler
leothedragon 0:25fa8795676b 136 *
leothedragon 0:25fa8795676b 137 * \param handler_func_ptr function pointer for event handler
leothedragon 0:25fa8795676b 138 * \param init_event_type generated event type for init purpose
leothedragon 0:25fa8795676b 139 *
leothedragon 0:25fa8795676b 140 * \return >= 0 Unique event ID for this handler
leothedragon 0:25fa8795676b 141 * \return < 0 Register fail
leothedragon 0:25fa8795676b 142 *
leothedragon 0:25fa8795676b 143 * */
leothedragon 0:25fa8795676b 144 extern int8_t eventOS_event_handler_create(void (*handler_func_ptr)(arm_event_t *), uint8_t init_event_type);
leothedragon 0:25fa8795676b 145
leothedragon 0:25fa8795676b 146 /**
leothedragon 0:25fa8795676b 147 * Cancel an event.
leothedragon 0:25fa8795676b 148 *
leothedragon 0:25fa8795676b 149 * Queued events are removed from the event-loop queue and/or the timer queue.
leothedragon 0:25fa8795676b 150 *
leothedragon 0:25fa8795676b 151 * Passing a NULL pointer is allowed, and does nothing.
leothedragon 0:25fa8795676b 152 *
leothedragon 0:25fa8795676b 153 * Event pointers are valid from the time they are queued until the event
leothedragon 0:25fa8795676b 154 * has finished running or is cancelled.
leothedragon 0:25fa8795676b 155 *
leothedragon 0:25fa8795676b 156 * Cancelling a currently-running event is only useful to stop scheduling
leothedragon 0:25fa8795676b 157 * it if it is on a periodic timer; it has no other effect.
leothedragon 0:25fa8795676b 158 *
leothedragon 0:25fa8795676b 159 * Cancelling an already-cancelled or already-run single-shot event
leothedragon 0:25fa8795676b 160 * is undefined behaviour.
leothedragon 0:25fa8795676b 161 *
leothedragon 0:25fa8795676b 162 * \param event Pointer to event handle or NULL.
leothedragon 0:25fa8795676b 163 */
leothedragon 0:25fa8795676b 164 extern void eventOS_cancel(arm_event_storage_t *event);
leothedragon 0:25fa8795676b 165
leothedragon 0:25fa8795676b 166 #ifdef __cplusplus
leothedragon 0:25fa8795676b 167 }
leothedragon 0:25fa8795676b 168 #endif
leothedragon 0:25fa8795676b 169 #endif /* EVENTOS_EVENT_H_ */