[apple/security.git] / libsecurity_asn1 / lib / prcvar.h

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Netscape Portable Runtime (NSPR).
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are 
 * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
 * Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL"), in which case the provisions of the GPL are applicable 
 * instead of those above.  If you wish to allow use of your 
 * version of this file only under the terms of the GPL and not to
 * allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by
 * the GPL.  If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

#ifndef prcvar_h___
#define prcvar_h___

#include <security_asn1/prlock.h>
#include <security_asn1/prinrval.h>

PR_BEGIN_EXTERN_C

typedef struct PRCondVar PRCondVar;

/*
** Create a new condition variable.
**
** 	"lock" is the lock used to protect the condition variable.
**
** Condition variables are synchronization objects that threads can use
** to wait for some condition to occur.
**
** This may fail if memory is tight or if some operating system resource
** is low. In such cases, a NULL will be returned.
*/
NSPR_API(PRCondVar*) PR_NewCondVar(PRLock *lock);

/*
** Destroy a condition variable. There must be no thread
** waiting on the condvar. The caller is responsible for guaranteeing
** that the condvar is no longer in use.
**
*/
NSPR_API(void) PR_DestroyCondVar(PRCondVar *cvar);

/*
** The thread that waits on a condition is blocked in a "waiting on
** condition" state until another thread notifies the condition or a
** caller specified amount of time expires. The lock associated with
** the condition variable will be released, which must have be held
** prior to the call to wait.
**
** Logically a notified thread is moved from the "waiting on condition"
** state and made "ready." When scheduled, it will attempt to reacquire
** the lock that it held when wait was called.
**
** The timeout has two well known values, PR_INTERVAL_NO_TIMEOUT and
** PR_INTERVAL_NO_WAIT. The former value requires that a condition be
** notified (or the thread interrupted) before it will resume from the
** wait. If the timeout has a value of PR_INTERVAL_NO_WAIT, the effect
** is to release the lock, possibly causing a rescheduling within the
** runtime, then immediately attempting to reacquire the lock and resume.
**
** Any other value for timeout will cause the thread to be rescheduled
** either due to explicit notification or an expired interval. The latter
** must be determined by treating time as one part of the monitored data
** being protected by the lock and tested explicitly for an expired
** interval.
**
** Returns PR_FAILURE if the caller has not locked the lock associated
** with the condition variable or the thread was interrupted (PR_Interrupt()).
** The particular reason can be extracted with PR_GetError().
*/
NSPR_API(PRStatus) PR_WaitCondVar(PRCondVar *cvar, PRIntervalTime timeout);

/*
** Notify ONE thread that is currently waiting on 'cvar'. Which thread is
** dependent on the implementation of the runtime. Common sense would dictate
** that all threads waiting on a single condition have identical semantics,
** therefore which one gets notified is not significant. 
**
** The calling thead must hold the lock that protects the condition, as
** well as the invariants that are tightly bound to the condition, when
** notify is called.
**
** Returns PR_FAILURE if the caller has not locked the lock associated
** with the condition variable.
*/
NSPR_API(PRStatus) PR_NotifyCondVar(PRCondVar *cvar);

/*
** Notify all of the threads waiting on the condition variable. The order
** that the threads are notified is indeterminant. The lock that protects
** the condition must be held.
**
** Returns PR_FAILURE if the caller has not locked the lock associated
** with the condition variable.
*/
NSPR_API(PRStatus) PR_NotifyAllCondVar(PRCondVar *cvar);

PR_END_EXTERN_C

#endif /* prcvar_h___ */
Commit	Line	Data
b1ab9ed8 A	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 Mozilla Public
	4	* License Version 1.1 (the "License"); you may not use this file
	5	* except in compliance with the License. You may obtain a copy of
	6	* the License at http://www.mozilla.org/MPL/
	7	*
	8	* Software distributed under the License is distributed on an "AS
	9	* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
	10	* implied. See the License for the specific language governing
	11	* rights and limitations under the License.
	12	*
	13	* The Original Code is the Netscape Portable Runtime (NSPR).
	14	*
	15	* The Initial Developer of the Original Code is Netscape
	16	* Communications Corporation. Portions created by Netscape are
	17	* Copyright (C) 1998-2000 Netscape Communications Corporation. All
	18	* Rights Reserved.
	19	*
	20	* Contributor(s):
	21	*
	22	* Alternatively, the contents of this file may be used under the
	23	* terms of the GNU General Public License Version 2 or later (the
	24	* "GPL"), in which case the provisions of the GPL are applicable
	25	* instead of those above. If you wish to allow use of your
	26	* version of this file only under the terms of the GPL and not to
	27	* allow others to use your version of this file under the MPL,
	28	* indicate your decision by deleting the provisions above and
	29	* replace them with the notice and other provisions required by
	30	* the GPL. If you do not delete the provisions above, a recipient
	31	* may use your version of this file under either the MPL or the
	32	* GPL.
	33	*/
	34
	35	#ifndef prcvar_h___
	36	#define prcvar_h___
	37
	38	#include <security_asn1/prlock.h>
	39	#include <security_asn1/prinrval.h>
	40
	41	PR_BEGIN_EXTERN_C
	42
	43	typedef struct PRCondVar PRCondVar;
	44
	45	/*
	46	** Create a new condition variable.
	47	**
	48	** "lock" is the lock used to protect the condition variable.
	49	**
	50	** Condition variables are synchronization objects that threads can use
	51	** to wait for some condition to occur.
	52	**
	53	** This may fail if memory is tight or if some operating system resource
	54	** is low. In such cases, a NULL will be returned.
	55	*/
	56	NSPR_API(PRCondVar) PR_NewCondVar(PRLock lock);
	57
	58	/*
	59	** Destroy a condition variable. There must be no thread
	60	** waiting on the condvar. The caller is responsible for guaranteeing
	61	** that the condvar is no longer in use.
	62	**
	63	*/
	64	NSPR_API(void) PR_DestroyCondVar(PRCondVar *cvar);
65
66	/*
67	** The thread that waits on a condition is blocked in a "waiting on
68	** condition" state until another thread notifies the condition or a
69	** caller specified amount of time expires. The lock associated with
70	** the condition variable will be released, which must have be held
71	** prior to the call to wait.
72	**
73	** Logically a notified thread is moved from the "waiting on condition"
74	** state and made "ready." When scheduled, it will attempt to reacquire
75	** the lock that it held when wait was called.
76	**
77	** The timeout has two well known values, PR_INTERVAL_NO_TIMEOUT and
78	** PR_INTERVAL_NO_WAIT. The former value requires that a condition be
79	** notified (or the thread interrupted) before it will resume from the
80	** wait. If the timeout has a value of PR_INTERVAL_NO_WAIT, the effect
81	** is to release the lock, possibly causing a rescheduling within the
82	** runtime, then immediately attempting to reacquire the lock and resume.
83	**
84	** Any other value for timeout will cause the thread to be rescheduled
85	** either due to explicit notification or an expired interval. The latter
86	** must be determined by treating time as one part of the monitored data
87	** being protected by the lock and tested explicitly for an expired
88	** interval.
89	**
90	** Returns PR_FAILURE if the caller has not locked the lock associated
91	** with the condition variable or the thread was interrupted (PR_Interrupt()).
92	** The particular reason can be extracted with PR_GetError().
93	*/
94	NSPR_API(PRStatus) PR_WaitCondVar(PRCondVar *cvar, PRIntervalTime timeout);
95
96	/*
97	** Notify ONE thread that is currently waiting on 'cvar'. Which thread is
98	** dependent on the implementation of the runtime. Common sense would dictate
99	** that all threads waiting on a single condition have identical semantics,
100	** therefore which one gets notified is not significant.
101	**
102	** The calling thead must hold the lock that protects the condition, as
103	** well as the invariants that are tightly bound to the condition, when
104	** notify is called.
105	**
106	** Returns PR_FAILURE if the caller has not locked the lock associated
107	** with the condition variable.
108	*/
109	NSPR_API(PRStatus) PR_NotifyCondVar(PRCondVar *cvar);
110
111	/*
112	** Notify all of the threads waiting on the condition variable. The order
113	** that the threads are notified is indeterminant. The lock that protects
114	** the condition must be held.
115	**
116	** Returns PR_FAILURE if the caller has not locked the lock associated
117	** with the condition variable.
118	*/
119	NSPR_API(PRStatus) PR_NotifyAllCondVar(PRCondVar *cvar);
120
121	PR_END_EXTERN_C
122
123	#endif /* prcvar_h___ */