periodic_event.h (5892B)
1 2 /* 3 * 4 * This license is set out in https://raw.githubusercontent.com/Broadcom-Network-Switching-Software/OpenBCM/master/Legal/LICENSE file. 5 * 6 * Copyright 2007-2019 Broadcom Inc. All rights reserved. 7 * 8 * File: periodic_event.h 9 * Purpose: Generic mechanisem for periodic events. 10 */ 11 12 /** 13 * 14 * The purpose of this package is to provide an easy way to 15 * create a thread for periodic event. 16 * 17 * A periodic event can be created by using 18 * periodic_event_create, by giving: 19 * -. name 20 * -. interval 21 * -. callback for periodic execution. 22 * 23 * Additional facilities given by this package: 24 * -. Having the ability to trigger the thread for immediate 25 * operation. 26 * -. Having the ability to start\stop the thread. 27 * -. Having the ability to send void* user data for the 28 * callback usage. 29 * -. Providing thread priority. 30 * -. Having error threshold - if the callback failed X time 31 * thread will automatically exit. 32 * 33 * Notes: 34 * -. To free allocated memory periodic_event_destroy should be 35 * called when periodic is no longer required, or upon deinit. 36 * -. Non of the information is WB protected - periodic event 37 * must be re-created after WB. 38 */ 39 40 #ifndef _SHR_PERIODIC_EVENT_H 41 #define _SHR_PERIODIC_EVENT_H 42 43 #include <sal/types.h> 44 #include <shared/error.h> 45 46 /** 47 * \brief - Handler for periodic event operations. 48 * To create a handle use periodic_event_create function. 49 */ 50 typedef void* periodic_event_handler_t; 51 52 /** 53 * \brief - Callback definition for periodic event 54 */ 55 typedef _shr_error_t (*periodic_event_f)(int unit, void* user_data); 56 57 /** 58 * \brief - Periodic Event configuration 59 */ 60 typedef struct periodic_event_config_s { 61 /** 62 * Periodic event name 63 */ 64 char* name; 65 66 /** 67 * BSL module that will be used for logging messages. 68 * It's very recommended to use meaningful bsl module from 69 * bslenum.h modules. 70 */ 71 uint32 bsl_module; 72 73 /** 74 * periodic interval in microseconds (usec) 75 * a value of sal_sem_FOREVER can be used to wait for trigger, 76 * instead of having periodic event. 77 * (see sal/core/sync.h) 78 */ 79 int interval; 80 81 /** 82 * Callback for the periodic operation 83 */ 84 periodic_event_f callback; 85 86 /** 87 * The user data will be passed to the periodic callback as is. 88 * periodic_event_config_t_init initialize user_data to 89 * null. 90 */ 91 void* user_data; 92 93 /** 94 * Thread scheduling priority (0 = highest, 255 = lowest) 95 * periodic_event_config_t_init initialize this parameter 96 * to default 50. (see sal/core/thread.h) 97 */ 98 int thread_priority; 99 100 /** 101 * When callback returns an error more than error_threshold in a 102 * raw the thread will exit. 103 * A value of -1 can be used to ignore callback errors. 104 * periodic_event_config_t_init initialize error_threadhold to 105 * -1 106 */ 107 int error_threshold; 108 109 /** 110 * Indicates whether to start running the periodic thread as 111 * part of create. 112 * periodic_event_config_t_init initialize this parameter to 113 * default 1. 114 */ 115 int start_operation; 116 } periodic_event_config_t; 117 118 /** 119 * \brief - initialize periodic_event_config_t struct 120 * \param [out] config - the structure to be initialized. 121 * \return 122 * See shr_error_e 123 * \remarks 124 * * Name, interval, callback and bsl_module must be set after 125 * struct initialization. The rest of the parameters are set with 126 * usable default. 127 * \see 128 * * None 129 */ 130 void periodic_event_config_t_init(periodic_event_config_t* config); 131 132 /** 133 * \brief - Create periodic event 134 * \param [in] unit - unit #. 135 * \param [in] config - see periodic_event_config_t for details. 136 * \param [out] h - handler for further operations on this 137 * periodic event object. 138 * \return 139 * See shr_error_e 140 * \remarks 141 * * This operation allocates memory. To free the allocated 142 * memory use periodic_event_destroy. 143 * * This operation creates a thread per create call. 144 * \see 145 * * None 146 */ 147 int periodic_event_create(int unit, const periodic_event_config_t* config, periodic_event_handler_t* h); 148 149 /** 150 * \brief - destroy the periodic event. 151 */ 152 int periodic_event_destroy(periodic_event_handler_t* h); 153 154 /** 155 * \brief - trigget the periodic event operation. 156 */ 157 int periodic_event_trigger(periodic_event_handler_t h); 158 159 /** 160 * \brief - start the periodic event. 161 */ 162 int periodic_event_start(periodic_event_handler_t h); 163 164 /** 165 * \brief - stop the periodic event. 166 * \param [in] dont_wait - indicate the thread to stop the next time it is triggered, 167 * don't wait for it to trigger. 168 * * if dont_wait is 1 the thread will stop next time it is triggered. 169 * * if dont_wait is 0 the thread will wait till it is triggered. 170 * \note the function will return error in case thread can't 171 * exit gracefully. 172 */ 173 int periodic_event_stop(periodic_event_handler_t h, int dont_wait); 174 175 /** 176 * \brief - determines whether event is active. 177 */ 178 int periodic_event_is_active_get(periodic_event_handler_t h, int* is_active); 179 180 /** 181 * \brief - update event interval 182 * (See interval on periodic_event_config_t for details) 183 */ 184 int periodic_event_interval_set(periodic_event_handler_t h, int interval); 185 186 /** 187 * \brief - get event interval 188 */ 189 int periodic_event_interval_get(periodic_event_handler_t h, int* interval); 190 191 /** 192 * \brief - whether current thread is in the periodic context 193 * (means it was called from periodic event callback) 194 */ 195 int periodic_event_is_periodic_context_get(periodic_event_handler_t h, int* is_periodic_context); 196 197 /** 198 * \brief - Indicate whether the periodic event has been 199 * signaled to quit. 200 */ 201 int periodic_event_is_quit_signaled_get(periodic_event_handler_t h, int* is_quit_signaled); 202 203 #endif /* _SHR_PERIODIC_EVENT_H */