home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nspr30-e.zip / nspr30-e / include / prcvar.h < prev    next >
C/C++ Source or Header  |  1998-07-21  |  4KB  |  108 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /*
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. #ifndef prcvar_h___
  20. #define prcvar_h___
  21.  
  22. #include "prlock.h"
  23. #include "prinrval.h"
  24.  
  25. PR_BEGIN_EXTERN_C
  26.  
  27. typedef struct PRCondVar PRCondVar;
  28.  
  29. /*
  30. ** Create a new condition variable.
  31. **
  32. **     "lock" is the lock used to protect the condition variable.
  33. **
  34. ** Condition variables are synchronization objects that threads can use
  35. ** to wait for some condition to occur.
  36. **
  37. ** This may fail if memory is tight or if some operating system resource
  38. ** is low. In such cases, a NULL will be returned.
  39. */
  40. PR_EXTERN(PRCondVar*) PR_NewCondVar(PRLock *lock);
  41.  
  42. /*
  43. ** Destroy a condition variable. There must be no thread
  44. ** waiting on the condvar. The caller is responsible for guaranteeing
  45. ** that the condvar is no longer in use.
  46. **
  47. */
  48. PR_EXTERN(void) PR_DestroyCondVar(PRCondVar *cvar);
  49.  
  50. /*
  51. ** The thread that waits on a condition is blocked in a "waiting on
  52. ** condition" state until another thread notifies the condition or a
  53. ** caller specified amount of time expires. The lock associated with
  54. ** the condition variable will be released, which must have be held
  55. ** prior to the call to wait.
  56. **
  57. ** Logically a notified thread is moved from the "waiting on condition"
  58. ** state and made "ready." When scheduled, it will attempt to reacquire
  59. ** the lock that it held when wait was called.
  60. **
  61. ** The timeout has two well known values, PR_INTERVAL_NO_TIMEOUT and
  62. ** PR_INTERVAL_NO_WAIT. The former value requires that a condition be
  63. ** notified (or the thread interrupted) before it will resume from the
  64. ** wait. If the timeout has a value of PR_INTERVAL_NO_WAIT, the effect
  65. ** is to release the lock, possibly causing a rescheduling within the
  66. ** runtime, then immediately attempting to reacquire the lock and resume.
  67. **
  68. ** Any other value for timeout will cause the thread to be rescheduled
  69. ** either due to explicit notification or an expired interval. The latter
  70. ** must be determined by treating time as one part of the monitored data
  71. ** being protected by the lock and tested explicitly for an expired
  72. ** interval.
  73. **
  74. ** Returns PR_FAILURE if the caller has not locked the lock associated
  75. ** with the condition variable or the thread was interrupted (PR_Interrupt()).
  76. ** The particular reason can be extracted with PR_GetError().
  77. */
  78. PR_EXTERN(PRStatus) PR_WaitCondVar(PRCondVar *cvar, PRIntervalTime timeout);
  79.  
  80. /*
  81. ** Notify ONE thread that is currently waiting on 'cvar'. Which thread is
  82. ** dependent on the implementation of the runtime. Common sense would dictate
  83. ** that all threads waiting on a single condition have identical semantics,
  84. ** therefore which one gets notified is not significant. 
  85. **
  86. ** The calling thead must hold the lock that protects the condition, as
  87. ** well as the invariants that are tightly bound to the condition, when
  88. ** notify is called.
  89. **
  90. ** Returns PR_FAILURE if the caller has not locked the lock associated
  91. ** with the condition variable.
  92. */
  93. PR_EXTERN(PRStatus) PR_NotifyCondVar(PRCondVar *cvar);
  94.  
  95. /*
  96. ** Notify all of the threads waiting on the condition variable. The order
  97. ** that the threads are notified is indeterminant. The lock that protects
  98. ** the condition must be held.
  99. **
  100. ** Returns PR_FAILURE if the caller has not locked the lock associated
  101. ** with the condition variable.
  102. */
  103. PR_EXTERN(PRStatus) PR_NotifyAllCondVar(PRCondVar *cvar);
  104.  
  105. PR_END_EXTERN_C
  106.  
  107. #endif /* prcvar_h___ */
  108.