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 } vce_event_handler_reg_t;
  57
  58 typedef struct vce_event_thread_
  59 {
  60   pthread_t thread;
  61   pthread_mutex_t generator_lock;
  62   pthread_cond_t generator_cond;
  63   u32 *event_index_fifo;
  64   u8 recycle_event;
  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
  70 } vce_event_thread_t;
  71
  72 /**
  73  * @brief vce_generate_event
  74  * - used to trigger an event in the event thread so that registered
  75  *   handlers are notified
  76  *
  77  * @param evt - vce_event_thread_t - event system state
  78  * @param ev_idx - index to vce_event_thread_t vce_event pool
  79  *
  80  * @return success/failure rv
  81  */
  82 int vce_generate_event (vce_event_thread_t *evt, u32 ev_idx);
  83
  84 /**
  85  * @brief vce_clear_event()
  86  * - removes event from event_pool
  87  *
  88  * @param evt - vce_event_thread_t - event system state
  89  * @param ev  - vce_event_t - event to remove
  90  */
  91 void vce_clear_event (vce_event_thread_t *evt, vce_event_t *ev);
  92
  93 /**
  94  * @brief vce_get_event_from_index()
  95  *
  96  * @param evt - vce_event_thread_t - event system state
  97  * @param ev_idx - index to vce_event_thread_t vce_event pool
  98  *
  99  * @return vce_event_t *
 100  */
 101 vce_event_t * vce_get_event_from_index(vce_event_thread_t *evt, u32 ev_idx);
 102
 103 /**
 104  * @brief vce_get_event_handler()
 105  * - returns handler if exists or 0
 106  * @param evt - vce_event_thread_t - event system state
 107  * @param evk - event key
 108  * @return vce_event_handler_reg_t *
 109  */
 110 vce_event_handler_reg_t * vce_get_event_handler (vce_event_thread_t *evt,
 111                                                  vce_event_key_t *evk);
 112
 113 /**
 114  * @brief vce_register_handler
 115  * - used by functions who need to be notified that an event has occurred
 116  *   on a vce_event_key_t (i.e. event type (enum) and sessionID)
 117  * - if a handler already exists, the index to the old handler is stored
 118  *   inside the new handler for re-instatement on vce_unregister_handler()
 119
 120  * @param evt - vce_event_thread_t - event system state
 121  * @param evk - vce_event_key_t current an eventID from enum in consumer and
 122  *              sessionID
 123  * @param cb  - vce_event_callback_t function to handle event
 124  * @return vce_handler_reg_t - the function that needs event notification
 125  *   needs to block on a condvar mutex to reduce spin. That is in here.
 126  */
 127 vce_event_handler_reg_t * vce_register_handler (vce_event_thread_t *evt,
 128                                                 vce_event_key_t *evk,
 129                                                 vce_event_callback_t cb);
 130
 131 /**
 132  * @brief vce_unregister_handler
 133  * - used by functions to remove need to be notified that an event has occurred
 134  *   on a vce_event_key_t (i.e. event type (enum) and sessionID)
 135  * - if this handler replaced an existing one, re-instate it.
 136  *
 137  * @param evt - vce_event_thread_t - event system state
 138  * @param handler - handler to be unregistered
 139  * @return success/failure rv
 140  */
 141 int vce_unregister_handler (vce_event_thread_t *evt,
 142                             vce_event_handler_reg_t *handler);
 143
 144 /**
 145  * @brief vce_event_thread_fn
 146  * - main event thread that waits on a generic condvar/mutex that a signal
 147  *   has been generated.
 148  *   - loops through all registered handlers for that vce_event_key_t
 149  *   (event enum + sessionID)
 150  *
 151  * @param arg - cast to type of event defined in consuming program.
 152  * @return
 153  */
 154 extern void * vce_event_thread_fn (void *arg);
 155
 156 /**
 157  * @brief vce_start_event_thread
 158  * - as name suggests. What is important is that vce_event_thread_t is allocated
 159  * on the same heap as "everything else". ie use clib_mem_alloc.
 160  * @param evt - vce_event_thread_t - event system state
 161  * @param max_events - depth of event FIFO for max number of outstanding events.
 162  * @return succes/failure
 163  */
 164 int vce_start_event_thread (vce_event_thread_t *evt, u8 max_events);
 165
 166 #endif //VPP_VCL_EVENT_H