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;
55 u32 replaced_handler_idx;
56 } vce_event_handler_reg_t;
58 typedef struct vce_event_thread_
61 pthread_mutex_t generator_lock;
62 pthread_cond_t generator_cond;
63 u32 *event_index_fifo;
65 clib_spinlock_t events_lockp;
66 vce_event_t *vce_events; //pool
67 clib_spinlock_t handlers_lockp;
68 vce_event_handler_reg_t *vce_event_handlers; //pool
69 uword *handlers_index_by_event_key; //hash
73 * @brief vce_generate_event
74 * - used to trigger an event in the event thread so that registered
75 * handlers are notified
77 * @param evt - vce_event_thread_t - event system state
78 * @param ev_idx - index to vce_event_thread_t vce_event pool
80 * @return success/failure rv
82 int vce_generate_event (vce_event_thread_t *evt, u32 ev_idx);
85 * @brief vce_clear_event()
86 * - removes event from event_pool
88 * @param evt - vce_event_thread_t - event system state
89 * @param ev - vce_event_t - event to remove
91 void vce_clear_event (vce_event_thread_t *evt, vce_event_t *ev);
94 * @brief vce_get_event_from_index()
96 * @param evt - vce_event_thread_t - event system state
97 * @param ev_idx - index to vce_event_thread_t vce_event pool
99 * @return vce_event_t *
101 vce_event_t * vce_get_event_from_index(vce_event_thread_t *evt, u32 ev_idx);
104 * @brief vce_register_handler
105 * - used by functions who need to be notified that an event has occurred
106 * on a vce_event_key_t (i.e. event type (enum) and sessionID)
107 * - if a handler already exists, the index to the old handler is stored
108 * inside the new handler for re-instatement on vce_unregister_handler()
110 * @param evt - vce_event_thread_t - event system state
111 * @param evk - vce_event_key_t current an eventID from enum in consumer and
113 * @param cb - vce_event_callback_t function to handle event
114 * @return vce_handler_reg_t - the function that needs event notification
115 * needs to block on a condvar mutex to reduce spin. That is in here.
117 vce_event_handler_reg_t * vce_register_handler (vce_event_thread_t *evt,
118 vce_event_key_t *evk,
119 vce_event_callback_t cb);
122 * @brief vce_unregister_handler
123 * - used by functions to remove need to be notified that an event has occurred
124 * on a vce_event_key_t (i.e. event type (enum) and sessionID)
125 * - if this handler replaced an existing one, re-instate it.
127 * @param evt - vce_event_thread_t - event system state
128 * @param handler - handler to be unregistered
129 * @return success/failure rv
131 int vce_unregister_handler (vce_event_thread_t *evt,
132 vce_event_handler_reg_t *handler);
135 * @brief vce_event_thread_fn
136 * - main event thread that waits on a generic condvar/mutex that a signal
137 * has been generated.
138 * - loops through all registered handlers for that vce_event_key_t
139 * (event enum + sessionID)
141 * @param arg - cast to type of event defined in consuming program.
144 extern void * vce_event_thread_fn (void *arg);
147 * @brief vce_start_event_thread
148 * - as name suggests. What is important is that vce_event_thread_t is allocated
149 * on the same heap as "everything else". ie use clib_mem_alloc.
150 * @param evt - vce_event_thread_t - event system state
151 * @param max_events - depth of event FIFO for max number of outstanding events.
152 * @return succes/failure
154 int vce_start_event_thread (vce_event_thread_t *evt, u8 max_events);
156 #endif //VPP_VCL_EVENT_H