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   u32 replaced_handler_idx;
  55 } vce_event_handler_reg_t;
  56
  57 typedef struct vce_event_thread_
  58 {
  59   pthread_t thread;
  60   pthread_mutex_t generator_lock;
  61   pthread_cond_t generator_cond;
  62   u32 *event_index_fifo;
  63   u8 recycle_event;
  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
  69 } vce_event_thread_t;
  70
  71 /**
  72  * @brief vce_generate_event
  73  * - used to trigger an event in the event thread so that registered
  74  *   handlers are notified
  75  *
  76  * @param evt - vce_event_thread_t - event system state
  77  * @param ev_idx - index to vce_event_thread_t vce_event pool
  78  *
  79  * @return success/failure rv
  80  */
  81 int vce_generate_event (vce_event_thread_t *evt, u32 ev_idx);
  82
  83 /**
  84  * @brief vce_clear_event()
  85  * - removes event from event_pool
  86  *
  87  * @param evt - vce_event_thread_t - event system state
  88  * @param ev  - vce_event_t - event to remove
  89  */
  90 void vce_clear_event (vce_event_thread_t *evt, vce_event_t *ev);
  91
  92 /**
  93  * @brief vce_get_event_from_index()
  94  *
  95  * @param evt - vce_event_thread_t - event system state
  96  * @param ev_idx - index to vce_event_thread_t vce_event pool
  97  *
  98  * @return vce_event_t *
  99  */
 100 vce_event_t * vce_get_event_from_index(vce_event_thread_t *evt, u32 ev_idx);
 101
 102 /**
 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()
 108
 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
 111  *              sessionID
 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.
 115  */
 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);
 119
 120 /**
 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.
 125  *
 126  * @param evt - vce_event_thread_t - event system state
 127  * @param ev  - vce_event_t - event to remove
 128  * @return success/failure rv
 129  */
 130 int vce_unregister_handler (vce_event_thread_t *evt, vce_event_t *ev);
 131
 132 /**
 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)
 138  *
 139  * @param arg - cast to type of event defined in consuming program.
 140  * @return
 141  */
 142 extern void * vce_event_thread_fn (void *arg);
 143
 144 /**
 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
 151  */
 152 int vce_start_event_thread (vce_event_thread_t *evt, u8 max_events);
 153
 154 #endif //VPP_VCL_EVENT_H