leo hendrickson / Mbed OS example-Ethernet-mbed-Cloud-connect

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.

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

Committer:
leothedragon
Date:
Tue May 04 08:55:12 2021 +0000
Revision:
0:8f0bb79ddd48
nmn

Who changed what in which revision?

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