VCL API for external callback for listener/connect event
[vpp.git] / src / vcl / vcl_event.h
1 /*
2  * Copyright (c) 2018 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this
5  * You may obtain a copy of the License at:
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
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.
14  */
15
16 #ifndef VPP_VCL_EVENT_H
17 #define VPP_VCL_EVENT_H
18
19 /**
20  * @file
21  * @brief VPP Communications Library (VCL) event handler.
22  *
23  * Declarations for generic event handling in VCL.
24  */
25
26 #include <vppinfra/types.h>
27 #include <vppinfra/lock.h>
28 #include <pthread.h>
29
30 typedef union vce_event_key_
31 {
32   struct {
33     u32 eid;
34     u32 session_index;
35   };
36   u64 as_u64;
37 } vce_event_key_t;
38
39 typedef struct vce_event_
40 {
41   vce_event_key_t evk;
42   u32 refcnt;
43   void *data;
44 } vce_event_t;
45
46 typedef void (*vce_event_callback_t) (void *reg /*vce_event_handler_reg_t* */);
47
48 typedef struct vce_event_handler_reg_
49 {
50   vce_event_callback_t handler_fn;
51   pthread_mutex_t handler_lock;
52   pthread_cond_t handler_cond;
53   u32 ev_idx;
54   u64 evk; //Event key
55   u32 replaced_handler_idx;
56   void *handler_fn_args;
57 } vce_event_handler_reg_t;
58
59 typedef struct vce_event_thread_
60 {
61   pthread_t thread;
62   pthread_mutex_t generator_lock;
63   pthread_cond_t generator_cond;
64   u32 *event_index_fifo;
65   u8 recycle_event;
66   clib_spinlock_t events_lockp;
67   vce_event_t *vce_events; //pool
68   clib_spinlock_t handlers_lockp;
69   vce_event_handler_reg_t *vce_event_handlers; //pool
70   uword *handlers_index_by_event_key; //hash
71 } vce_event_thread_t;
72
73 /**
74  * @brief vce_generate_event
75  * - used to trigger an event in the event thread so that registered
76  *   handlers are notified
77  *
78  * @param evt - vce_event_thread_t - event system state
79  * @param ev_idx - index to vce_event_thread_t vce_event pool
80  *
81  * @return success/failure rv
82  */
83 int vce_generate_event (vce_event_thread_t *evt, u32 ev_idx);
84
85 /**
86  * @brief vce_clear_event()
87  * - removes event from event_pool
88  *
89  * @param evt - vce_event_thread_t - event system state
90  * @param ev  - vce_event_t - event to remove
91  */
92 void vce_clear_event (vce_event_thread_t *evt, vce_event_t *ev);
93
94 /**
95  * @brief vce_get_event_from_index()
96  *
97  * @param evt - vce_event_thread_t - event system state
98  * @param ev_idx - index to vce_event_thread_t vce_event pool
99  *
100  * @return vce_event_t *
101  */
102 vce_event_t * vce_get_event_from_index(vce_event_thread_t *evt, u32 ev_idx);
103
104 /**
105  * @brief vce_get_event_handler()
106  * - returns handler if exists or 0
107  * @param evt - vce_event_thread_t - event system state
108  * @param evk - event key
109  * @return vce_event_handler_reg_t *
110  */
111 vce_event_handler_reg_t * vce_get_event_handler (vce_event_thread_t *evt,
112                                                  vce_event_key_t *evk);
113
114 /**
115  * @brief vce_register_handler
116  * - used by functions who need to be notified that an event has occurred
117  *   on a vce_event_key_t (i.e. event type (enum) and sessionID)
118  * - if a handler already exists, the index to the old handler is stored
119  *   inside the new handler for re-instatement on vce_unregister_handler()
120
121  * @param evt - vce_event_thread_t - event system state
122  * @param evk - vce_event_key_t current an eventID from enum in consumer and
123  *              sessionID
124  * @param cb  - vce_event_callback_t function to handle event
125  * @param cb_args - args that the callback needs passed back to it.
126  * @return vce_handler_reg_t - the function that needs event notification
127  *   needs to block on a condvar mutex to reduce spin. That is in here.
128  */
129 vce_event_handler_reg_t * vce_register_handler (vce_event_thread_t *evt,
130                                                 vce_event_key_t *evk,
131                                                 vce_event_callback_t cb,
132                                                 void *cb_args);
133
134 /**
135  * @brief vce_unregister_handler
136  * - used by functions to remove need to be notified that an event has occurred
137  *   on a vce_event_key_t (i.e. event type (enum) and sessionID)
138  * - if this handler replaced an existing one, re-instate it.
139  *
140  * @param evt - vce_event_thread_t - event system state
141  * @param handler - handler to be unregistered
142  * @return success/failure rv
143  */
144 int vce_unregister_handler (vce_event_thread_t *evt,
145                             vce_event_handler_reg_t *handler);
146
147 /**
148  * @brief vce_event_thread_fn
149  * - main event thread that waits on a generic condvar/mutex that a signal
150  *   has been generated.
151  *   - loops through all registered handlers for that vce_event_key_t
152  *   (event enum + sessionID)
153  *
154  * @param arg - cast to type of event defined in consuming program.
155  * @return
156  */
157 extern void * vce_event_thread_fn (void *arg);
158
159 /**
160  * @brief vce_start_event_thread
161  * - as name suggests. What is important is that vce_event_thread_t is allocated
162  * on the same heap as "everything else". ie use clib_mem_alloc.
163  * @param evt - vce_event_thread_t - event system state
164  * @param max_events - depth of event FIFO for max number of outstanding events.
165  * @return succes/failure
166  */
167 int vce_start_event_thread (vce_event_thread_t *evt, u8 max_events);
168
169 #endif //VPP_VCL_EVENT_H