include/iprt/condvar.h

   1 /** @file
   2  * IPRT - Condition Variable.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2024 Oracle and/or its affiliates.
   7  *
   8  * This file is part of VirtualBox base platform packages, as
   9  * available from https://www.virtualbox.org.
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation, in version 3 of the
  14  * License.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, see <https://www.gnu.org/licenses>.
  23  *
  24  * The contents of this file may alternatively be used under the terms
  25  * of the Common Development and Distribution License Version 1.0
  26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  27  * in the VirtualBox distribution, in which case the provisions of the
  28  * CDDL are applicable instead of those of the GPL.
  29  *
  30  * You may elect to license modified versions of this file under the
  31  * terms and conditions of either the GPL or the CDDL or both.
  32  *
  33  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  34  */
  35
  36 #ifndef IPRT_INCLUDED_condvar_h
  37 #define IPRT_INCLUDED_condvar_h
  38 #ifndef RT_WITHOUT_PRAGMA_ONCE
  39 # pragma once
  40 #endif
  41
  42 #include <iprt/cdefs.h>
  43 #include <iprt/types.h>
  44 #if defined(RT_LOCK_STRICT_ORDER) && defined(IN_RING3)
  45 # include <iprt/lockvalidator.h>
  46 #endif
  47
  48
  49 RT_C_DECLS_BEGIN
  50
  51 /** @defgroup grp_rt_condvar    RTCondVar - Condition Variable
  52  *
  53  * Condition variables combines mutex semaphore or critical sections with event
  54  * semaphores.  See @ref grp_rt_sems_mutex, @ref grp_rt_critsect,
  55  * @ref grp_rt_sems_event and @ref grp_rt_sems_event_multi.
  56  *
  57  * @ingroup grp_rt
  58  * @{
  59  */
  60
  61
  62 /**
  63  * Create a condition variable.
  64  *
  65  * @returns iprt status code.
  66  * @param   phCondVar           Where to store the handle to the newly created
  67  *                              condition variable.
  68  */
  69 RTDECL(int)  RTCondVarCreate(PRTCONDVAR phCondVar);
  70
  71 /**
  72  * Create a condition variable.
  73  *
  74  * @returns iprt status code.
  75  * @param   phCondVar           Where to store the handle to the newly created
  76  *                              condition variable.
  77  * @param   fFlags              Flags, any combination of the
  78  *                              RTCONDVAR_FLAGS_XXX \#defines.
  79  * @param   hClass              The class (no reference consumed).  Since we
  80  *                              don't do order checks on condition variables,
  81  *                              the use of the class is limited to controlling
  82  *                              the timeout threshold for deadlock detection.
  83  * @param   pszNameFmt          Name format string for the lock validator,
  84  *                              optional (NULL).  Max length is 32 bytes.
  85  * @param   ...                 Format string arguments.
  86  */
  87 RTDECL(int)  RTCondVarCreateEx(PRTCONDVAR phCondVar, uint32_t fFlags, RTLOCKVALCLASS hClass,
  88                                const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
  89
  90 /** @name RTCondVarCreateEx flags
  91  * @{ */
  92 /** Disables lock validation. */
  93 #define RTCONDVAR_FLAGS_NO_LOCK_VAL     UINT32_C(0x00000001)
  94 /** @} */
  95
  96 /**
  97  * Destroy a condition variable.
  98  *
  99  * @returns iprt status code.
 100  * @param   hCondVar            Handle of the condition variable.  NIL_RTCONDVAR
 101  *                              is quietly ignored (VINF_SUCCESS).
 102  */
 103 RTDECL(int)  RTCondVarDestroy(RTCONDVAR hCondVar);
 104
 105 /**
 106  * Signal the condition variable, waking up exactly one thread.
 107  *
 108  * It is recommended that the caller holds the associated lock, but this is not
 109  * strictly speaking necessary.
 110  *
 111  * If no threads are waiting on the condition variable, the call will have no
 112  * effect on the variable.
 113  *
 114  * @returns iprt status code.
 115  * @param   hCondVar            The condition variable to signal.
 116  */
 117 RTDECL(int)  RTCondVarSignal(RTCONDVAR hCondVar);
 118
 119 /**
 120  * Signal the condition variable, waking up all blocked threads.
 121  *
 122  * It is recommended that the caller holds the associated lock, but this is not
 123  * strictly speaking necessary.
 124  *
 125  * If no threads are waiting on the condition variable, the call will have no
 126  * effect on the variable.
 127  *
 128  * @returns iprt status code.
 129  * @param   hCondVar            The condition variable to broadcast.
 130  */
 131 RTDECL(int)  RTCondVarBroadcast(RTCONDVAR hCondVar);
 132
 133 /**
 134  * Wait for the condition variable to be signaled, resume on interruption.
 135  *
 136  * This function will resume if the wait is interrupted by an async system event
 137  * (like a unix signal) or similar.
 138  *
 139  * @returns iprt status code.
 140  *          Will not return VERR_INTERRUPTED.
 141  * @param   hCondVar            The condition variable to wait on.
 142  * @param   hMtx                The mutex to leave during the wait and which
 143  *                              will be re-enter before returning.
 144  * @param   cMillies            Number of milliseconds to wait.  Use
 145  *                              RT_INDEFINITE_WAIT to wait forever.
 146  */
 147 RTDECL(int)  RTCondVarMutexWait(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
 148
 149 /**
 150  * Wait for the condition variable to be signaled, return on interruption.
 151  *
 152  * This function will not resume the wait if interrupted.
 153  *
 154  * @returns iprt status code.
 155  * @param   hCondVar            The condition variable to wait on.
 156  * @param   hMtx                The mutex to leave during the wait and which
 157  *                              will be re-enter before returning.
 158  * @param   cMillies            Number of milliseconds to wait.  Use
 159  *                              RT_INDEFINITE_WAIT to wait forever.
 160  */
 161 RTDECL(int)  RTCondVarMutexWaitNoResume(RTCONDVAR hCondVar, RTSEMMUTEX hMtx, RTMSINTERVAL cMillies);
 162
 163 /**
 164  * Wait for the condition variable to be signaled, resume on interruption.
 165  *
 166  * This function will resume if the wait is interrupted by an async system event
 167  * (like a unix signal) or similar.
 168  *
 169  * @returns iprt status code.
 170  *          Will not return VERR_INTERRUPTED.
 171  * @param   hCondVar            The condition variable to wait on.
 172  * @param   hRWSem              The read/write semaphore to write-leave during
 173  *                              the wait and which will be re-enter in write
 174  *                              mode before returning.
 175  * @param   cMillies            Number of milliseconds to wait.  Use
 176  *                              RT_INDEFINITE_WAIT to wait forever.
 177  */
 178 RTDECL(int)  RTCondVarRWWriteWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
 179
 180 /**
 181  * Wait for the condition variable to be signaled, return on interruption.
 182  *
 183  * This function will not resume the wait if interrupted.
 184  *
 185  * @returns iprt status code.
 186  * @param   hCondVar            The condition variable to wait on.
 187  * @param   hRWSem              The read/write semaphore to write-leave during
 188  *                              the wait and which will be re-enter in write
 189  *                              mode before returning.
 190  * @param   cMillies            Number of milliseconds to wait.  Use
 191  *                              RT_INDEFINITE_WAIT to wait forever.
 192  */
 193 RTDECL(int)  RTCondVarRWWriteWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
 194
 195 /**
 196  * Wait for the condition variable to be signaled, resume on interruption.
 197  *
 198  * This function will resume if the wait is interrupted by an async system event
 199  * (like a unix signal) or similar.
 200  *
 201  * @returns iprt status code.
 202  *          Will not return VERR_INTERRUPTED.
 203  * @param   hCondVar            The condition variable to wait on.
 204  * @param   hRWSem              The read/write semaphore to read-leave during
 205  *                              the wait and which will be re-enter in read mode
 206  *                              before returning.
 207  * @param   cMillies            Number of milliseconds to wait.  Use
 208  *                              RT_INDEFINITE_WAIT to wait forever.
 209  */
 210 RTDECL(int)  RTCondVarRWReadWait(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
 211
 212 /**
 213  * Wait for the condition variable to be signaled, return on interruption.
 214  *
 215  * This function will not resume the wait if interrupted.
 216  *
 217  * @returns iprt status code.
 218  * @param   hCondVar            The condition variable to wait on.
 219  * @param   hRWSem              The read/write semaphore to read-leave during
 220  *                              the wait and which will be re-enter in read mode
 221  *                              before returning.
 222  * @param   cMillies            Number of milliseconds to wait.  Use
 223  *                              RT_INDEFINITE_WAIT to wait forever.
 224  */
 225 RTDECL(int)  RTCondVarRWReadWaitNoResume(RTCONDVAR hCondVar, RTSEMRW hRWSem, RTMSINTERVAL cMillies);
 226
 227 /**
 228  * Wait for the condition variable to be signaled, resume on interruption.
 229  *
 230  * This function will resume if the wait is interrupted by an async system event
 231  * (like a unix signal) or similar.
 232  *
 233  * @returns iprt status code.
 234  *          Will not return VERR_INTERRUPTED.
 235  * @param   hCondVar            The condition variable to wait on.
 236  * @param   pCritSect           The critical section to leave during the wait
 237  *                              and which will be re-enter before returning.
 238  * @param   cMillies            Number of milliseconds to wait.  Use
 239  *                              RT_INDEFINITE_WAIT to wait forever.
 240  */
 241 RTDECL(int)  RTCondVarCritSectWait(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
 242
 243 /**
 244  * Wait for the condition variable to be signaled, return on interruption.
 245  *
 246  * This function will not resume the wait if interrupted.
 247  *
 248  * @returns iprt status code.
 249  * @param   hCondVar            The condition variable to wait on.
 250  * @param   pCritSect           The critical section to leave during the wait
 251  *                              and which will be re-enter before returning.
 252  * @param   cMillies            Number of milliseconds to wait.  Use
 253  *                              RT_INDEFINITE_WAIT to wait forever.
 254  */
 255 RTDECL(int)  RTCondVarCritSectWaitNoResume(RTCONDVAR hCondVar, PRTCRITSECT pCritSect, RTMSINTERVAL cMillies);
 256
 257 /**
 258  * Sets the signaller thread to one specific thread.
 259  *
 260  * This is only used for validating usage and deadlock detection.  When used
 261  * after calls to RTCondVarAddSignaller, the specified thread will be the only
 262  * signalling thread.
 263  *
 264  * @param   hCondVar            The condition variable.
 265  * @param   hThread             The thread that will signal it.  Pass
 266  *                              NIL_RTTHREAD to indicate that there is no
 267  *                              special signalling thread.
 268  */
 269 RTDECL(void) RTCondVarSetSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
 270
 271 /**
 272  * To add more signalling threads.
 273  *
 274  * First call RTCondVarSetSignaller then add further threads with this.
 275  *
 276  * @param   hCondVar            The condition variable.
 277  * @param   hThread             The thread that will signal it. NIL_RTTHREAD is
 278  *                              not accepted.
 279  */
 280 RTDECL(void) RTCondVarAddSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
 281
 282 /**
 283  * To remove a signalling thread.
 284  *
 285  * Reverts work done by RTCondVarAddSignaller and RTCondVarSetSignaller.
 286  *
 287  * @param   hCondVar            The condition variable.
 288  * @param   hThread             A previously added thread.
 289  */
 290 RTDECL(void) RTCondVarRemoveSignaller(RTCONDVAR hCondVar, RTTHREAD hThread);
 291
 292 /** @} */
 293
 294 RT_C_DECLS_END
 295
 296 #endif /* !IPRT_INCLUDED_condvar_h */
 297