2 * Copyright (c) 2018 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 #ifndef VPP_VCL_EVENT_H
17 #define VPP_VCL_EVENT_H
21 * @brief VPP Communications Library (VCL) event handler.
23 * Declarations for generic event handling in VCL.
26 #include <vppinfra/types.h>
27 #include <vppinfra/lock.h>
30 typedef union vce_event_key_
39 typedef struct vce_event_
46 typedef void (*vce_event_callback_t) (void *reg /*vce_event_handler_reg_t* */);
48 typedef struct vce_event_handler_reg_
50 vce_event_callback_t handler_fn;
51 pthread_mutex_t handler_lock;
52 pthread_cond_t handler_cond;
54 u32 replaced_handler_idx;
55 } vce_event_handler_reg_t;
57 typedef struct vce_event_thread_
60 pthread_mutex_t generator_lock;
61 pthread_cond_t generator_cond;
62 u32 *event_index_fifo;
64 clib_spinlock_t events_lockp;
65 vce_event_t *vce_events; //pool
66 clib_spinlock_t handlers_lockp;
67 vce_event_handler_reg_t *vce_event_handlers; //pool
68 uword *handlers_index_by_event_key; //hash
72 * @brief vce_generate_event
73 * - used to trigger an event in the event thread so that registered
74 * handlers are notified
76 * @param evt - vce_event_thread_t - event system state
77 * @param ev_idx - index to vce_event_thread_t vce_event pool
79 * @return success/failure rv
81 int vce_generate_event (vce_event_thread_t *evt, u32 ev_idx);
84 * @brief vce_clear_event()
85 * - removes event from event_pool
87 * @param evt - vce_event_thread_t - event system state
88 * @param ev - vce_event_t - event to remove
90 void vce_clear_event (vce_event_thread_t *evt, vce_event_t *ev);
93 * @brief vce_get_event_from_index()
95 * @param evt - vce_event_thread_t - event system state
96 * @param ev_idx - index to vce_event_thread_t vce_event pool
98 * @return vce_event_t *
100 vce_event_t * vce_get_event_from_index(vce_event_thread_t *evt, u32 ev_idx);
103 * @brief vce_register_handler
104 * - used by functions who need to be notified that an event has occurred
105 * on a vce_event_key_t (i.e. event type (enum) and sessionID)
106 * - if a handler already exists, the index to the old handler is stored
107 * inside the new handler for re-instatement on vce_unregister_handler()
109 * @param evt - vce_event_thread_t - event system state
110 * @param evk - vce_event_key_t current an eventID from enum in consumer and
112 * @param cb - vce_event_callback_t function to handle event
113 * @return vce_handler_reg_t - the function that needs event notification
114 * needs to block on a condvar mutex to reduce spin. That is in here.
116 vce_event_handler_reg_t * vce_register_handler (vce_event_thread_t *evt,
117 vce_event_key_t *evk,
118 vce_event_callback_t cb);
121 * @brief vce_unregister_handler
122 * - used by functions to remove need to be notified that an event has occurred
123 * on a vce_event_key_t (i.e. event type (enum) and sessionID)
124 * - if this handler replaced an existing one, re-instate it.
126 * @param evt - vce_event_thread_t - event system state
127 * @param ev - vce_event_t - event to remove
128 * @return success/failure rv
130 int vce_unregister_handler (vce_event_thread_t *evt, vce_event_t *ev);
133 * @brief vce_event_thread_fn
134 * - main event thread that waits on a generic condvar/mutex that a signal
135 * has been generated.
136 * - loops through all registered handlers for that vce_event_key_t
137 * (event enum + sessionID)
139 * @param arg - cast to type of event defined in consuming program.
142 extern void * vce_event_thread_fn (void *arg);
145 * @brief vce_start_event_thread
146 * - as name suggests. What is important is that vce_event_thread_t is allocated
147 * on the same heap as "everything else". ie use clib_mem_alloc.
148 * @param evt - vce_event_thread_t - event system state
149 * @param max_events - depth of event FIFO for max number of outstanding events.
150 * @return succes/failure
152 int vce_start_event_thread (vce_event_thread_t *evt, u8 max_events);
154 #endif //VPP_VCL_EVENT_H