contrib/ofed/management/opensm/include/complib/cl_event.h

   1 /*
   2  * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
   3  * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
   4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
   5  *
   6  * This software is available to you under a choice of one of two
   7  * licenses.  You may choose to be licensed under the terms of the GNU
   8  * General Public License (GPL) Version 2, available from the file
   9  * COPYING in the main directory of this source tree, or the
  10  * OpenIB.org BSD license below:
  11  *
  12  *     Redistribution and use in source and binary forms, with or
  13  *     without modification, are permitted provided that the following
  14  *     conditions are met:
  15  *
  16  *      - Redistributions of source code must retain the above
  17  *        copyright notice, this list of conditions and the following
  18  *        disclaimer.
  19  *
  20  *      - Redistributions in binary form must reproduce the above
  21  *        copyright notice, this list of conditions and the following
  22  *        disclaimer in the documentation and/or other materials
  23  *        provided with the distribution.
  24  *
  25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  26  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  27  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  28  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  29  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  30  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  31  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  32  * SOFTWARE.
  33  *
  34  */
  35
  36 /*
  37  * Abstract:
  38  *      Declaration of event abstraction.
  39  */
  40
  41 #ifndef _CL_EVENT_H_
  42 #define _CL_EVENT_H_
  43
  44 /* Indicates that waiting on an event should never timeout */
  45 #define EVENT_NO_TIMEOUT        0xFFFFFFFF
  46
  47 #include <complib/cl_event_osd.h>
  48
  49 #ifdef __cplusplus
  50 #  define BEGIN_C_DECLS extern "C" {
  51 #  define END_C_DECLS   }
  52 #else                           /* !__cplusplus */
  53 #  define BEGIN_C_DECLS
  54 #  define END_C_DECLS
  55 #endif                          /* __cplusplus */
  56
  57 BEGIN_C_DECLS
  58 /****h* Component Library/Event
  59 * NAME
  60 *       Event
  61 *
  62 * DESCRIPTION
  63 *       The Event provides the ability to suspend and wakeup a thread.
  64 *
  65 *       The event functions operates on a cl_event_t structure which should be
  66 *       treated as opaque and should be manipulated only through the provided
  67 *       functions.
  68 *
  69 * SEE ALSO
  70 *       Structures:
  71 *               cl_event_t
  72 *
  73 *       Initialization/Destruction:
  74 *               cl_event_construct, cl_event_init, cl_event_destroy
  75 *
  76 *       Manipulation:
  77 *               cl_event_signal, cl_event_reset, cl_event_wait_on
  78 *********/
  79 /****f* Component Library: Event/cl_event_construct
  80 * NAME
  81 *       cl_event_construct
  82 *
  83 * DESCRIPTION
  84 *       The cl_event_construct function constructs an event.
  85 *
  86 * SYNOPSIS
  87 */
  88 void cl_event_construct(IN cl_event_t * const p_event);
  89 /*
  90 * PARAMETERS
  91 *       p_event
  92 *               [in] Pointer to an cl_event_t structure to construct.
  93 *
  94 * RETURN VALUE
  95 *       This function does not return a value.
  96 *
  97 * NOTES
  98 *       Allows calling cl_event_destroy without first calling cl_event_init.
  99 *
 100 *       Calling cl_event_construct is a prerequisite to calling any other event
 101 *       function except cl_event_init.
 102 *
 103 * SEE ALSO
 104 *       Event, cl_event_init, cl_event_destroy
 105 *********/
 106
 107 /****f* Component Library: Event/cl_event_init
 108 * NAME
 109 *       cl_event_init
 110 *
 111 * DESCRIPTION
 112 *       The cl_event_init function initializes an event for use.
 113 *
 114 * SYNOPSIS
 115 */
 116 cl_status_t
 117 cl_event_init(IN cl_event_t * const p_event, IN const boolean_t manual_reset);
 118 /*
 119 * PARAMETERS
 120 *       p_event
 121 *               [in] Pointer to an cl_event_t structure to initialize.
 122 *
 123 *       manual_reset
 124 *               [in] If FALSE, indicates that the event resets itself after releasing
 125 *               a single waiter.  If TRUE, the event remains in the signalled state
 126 *               until explicitly reset by a call to cl_event_reset.
 127 *
 128 * RETURN VALUES
 129 *       CL_SUCCESS if event initialization succeeded.
 130 *
 131 *       CL_ERROR otherwise.
 132 *
 133 * NOTES
 134 *       Allows calling event manipulation functions, such as cl_event_signal,
 135 *       cl_event_reset, and cl_event_wait_on.
 136 *
 137 *       The event is initially in a reset state.
 138 *
 139 * SEE ALSO
 140 *       Event, cl_event_construct, cl_event_destroy, cl_event_signal,
 141 *       cl_event_reset, cl_event_wait_on
 142 *********/
 143
 144 /****f* Component Library: Event/cl_event_destroy
 145 * NAME
 146 *       cl_event_destroy
 147 *
 148 * DESCRIPTION
 149 *       The cl_event_destroy function performs any necessary cleanup of an event.
 150 *
 151 * SYNOPSIS
 152 */
 153 void cl_event_destroy(IN cl_event_t * const p_event);
 154
 155 /*
 156 * PARAMETERS
 157 *       p_event
 158 *               [in] Pointer to an cl_event_t structure to destroy.
 159 *
 160 * RETURN VALUE
 161 *       This function does not return a value.
 162 *
 163 * NOTES
 164 *       This function should only be called after a call to cl_event_construct
 165 *       or cl_event_init.
 166 *
 167 * SEE ALSO
 168 *       Event, cl_event_construct, cl_event_init
 169 *********/
 170
 171 /****f* Component Library: Event/cl_event_signal
 172 * NAME
 173 *       cl_event_signal
 174 *
 175 * DESCRIPTION
 176 *       The cl_event_signal function sets an event to the signalled state and
 177 *       releases at most one waiting thread.
 178 *
 179 * SYNOPSIS
 180 */
 181 cl_status_t cl_event_signal(IN cl_event_t * const p_event);
 182 /*
 183 * PARAMETERS
 184 *       p_event
 185 *               [in] Pointer to an cl_event_t structure to set.
 186 *
 187 * RETURN VALUES
 188 *       CL_SUCCESS if the event was successfully signalled.
 189 *
 190 *       CL_ERROR otherwise.
 191 *
 192 * NOTES
 193 *       For auto-reset events, the event is reset automatically once a wait
 194 *       operation is satisfied.
 195 *
 196 *       Triggering the event multiple times does not guarantee that the same
 197 *       number of wait operations are satisfied. This is because events are
 198 *       either in a signalled on non-signalled state, and triggering an event
 199 *       that is already in the signalled state has no effect.
 200 *
 201 * SEE ALSO
 202 *       Event, cl_event_reset, cl_event_wait_on
 203 *********/
 204
 205 /****f* Component Library: Event/cl_event_reset
 206 * NAME
 207 *       cl_event_reset
 208 *
 209 * DESCRIPTION
 210 *       The cl_event_reset function sets an event to the non-signalled state.
 211 *
 212 * SYNOPSIS
 213 */
 214 cl_status_t cl_event_reset(IN cl_event_t * const p_event);
 215 /*
 216 * PARAMETERS
 217 *       p_event
 218 *               [in] Pointer to an cl_event_t structure to reset.
 219 *
 220 * RETURN VALUES
 221 *       CL_SUCCESS if the event was successfully reset.
 222 *
 223 *       CL_ERROR otherwise.
 224 *
 225 * SEE ALSO
 226 *       Event, cl_event_signal, cl_event_wait_on
 227 *********/
 228
 229 /****f* Component Library: Event/cl_event_wait_on
 230 * NAME
 231 *       cl_event_wait_on
 232 *
 233 * DESCRIPTION
 234 *       The cl_event_wait_on function waits for the specified event to be
 235 *       triggered for a minimum amount of time.
 236 *
 237 * SYNOPSIS
 238 */
 239 cl_status_t
 240 cl_event_wait_on(IN cl_event_t * const p_event,
 241                  IN const uint32_t wait_us, IN const boolean_t interruptible);
 242 /*
 243 * PARAMETERS
 244 *       p_event
 245 *               [in] Pointer to an cl_event_t structure on which to wait.
 246 *
 247 *       wait_us
 248 *               [in] Number of microseconds to wait.
 249 *
 250 *       interruptible
 251 *               [in] Indicates whether the wait operation can be interrupted
 252 *               by external signals.
 253 *
 254 * RETURN VALUES
 255 *       CL_SUCCESS if the wait operation succeeded in response to the event
 256 *       being set.
 257 *
 258 *       CL_TIMEOUT if the specified time period elapses.
 259 *
 260 *       CL_NOT_DONE if the wait was interrupted by an external signal.
 261 *
 262 *       CL_ERROR if the wait operation failed.
 263 *
 264 * NOTES
 265 *       If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the
 266 *       event is triggered and never timeout.
 267 *
 268 *       If the timeout value is zero, this function simply tests the state of
 269 *       the event.
 270 *
 271 *       If the event is already on the signalled state at the time of the call
 272 *       to cl_event_wait_on, the call completes immediately with CL_SUCCESS.
 273 *
 274 * SEE ALSO
 275 *       Event, cl_event_signal, cl_event_reset
 276 *********/
 277
 278 END_C_DECLS
 279 #endif                          /* _CL_EVENT_H_ */