Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* This Source Code Form is subject to the terms of the Mozilla Public
3 : * License, v. 2.0. If a copy of the MPL was not distributed with this
4 : * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 :
6 : /*
7 : ** File: prlock.h
8 : ** Description: API to basic locking functions of NSPR.
9 : **
10 : **
11 : ** NSPR provides basic locking mechanisms for thread synchronization. Locks
12 : ** are lightweight resource contention controls that prevent multiple threads
13 : ** from accessing something (code/data) simultaneously.
14 : **/
15 :
16 : #ifndef prlock_h___
17 : #define prlock_h___
18 :
19 : #include "prtypes.h"
20 :
21 : PR_BEGIN_EXTERN_C
22 :
23 : /**********************************************************************/
24 : /************************* TYPES AND CONSTANTS ************************/
25 : /**********************************************************************/
26 :
27 : /*
28 : * PRLock --
29 : *
30 : * NSPR represents the lock as an opaque entity to the client of the
31 : * API. All routines operate on a pointer to this opaque entity.
32 : */
33 :
34 : typedef struct PRLock PRLock;
35 :
36 : /**********************************************************************/
37 : /****************************** FUNCTIONS *****************************/
38 : /**********************************************************************/
39 :
40 : /***********************************************************************
41 : ** FUNCTION: PR_NewLock
42 : ** DESCRIPTION:
43 : ** Returns a pointer to a newly created opaque lock object.
44 : ** INPUTS: void
45 : ** OUTPUTS: void
46 : ** RETURN: PRLock*
47 : ** If the lock can not be created because of resource constraints, NULL
48 : ** is returned.
49 : **
50 : ***********************************************************************/
51 2193 : NSPR_API(PRLock*) PR_NewLock(void);
52 :
53 : /***********************************************************************
54 : ** FUNCTION: PR_DestroyLock
55 : ** DESCRIPTION:
56 : ** Destroys a given opaque lock object.
57 : ** INPUTS: PRLock *lock
58 : ** Lock to be freed.
59 : ** OUTPUTS: void
60 : ** RETURN: None
61 : ***********************************************************************/
62 1725 : NSPR_API(void) PR_DestroyLock(PRLock *lock);
63 :
64 : /***********************************************************************
65 : ** FUNCTION: PR_Lock
66 : ** DESCRIPTION:
67 : ** Lock a lock.
68 : ** INPUTS: PRLock *lock
69 : ** Lock to locked.
70 : ** OUTPUTS: void
71 : ** RETURN: None
72 : ***********************************************************************/
73 57343 : NSPR_API(void) PR_Lock(PRLock *lock);
74 :
75 : /***********************************************************************
76 : ** FUNCTION: PR_Unlock
77 : ** DESCRIPTION:
78 : ** Unlock a lock. Unlocking an unlocked lock has undefined results.
79 : ** INPUTS: PRLock *lock
80 : ** Lock to unlocked.
81 : ** OUTPUTS: void
82 : ** RETURN: PR_STATUS
83 : ** Returns PR_FAILURE if the caller does not own the lock.
84 : ***********************************************************************/
85 57350 : NSPR_API(PRStatus) PR_Unlock(PRLock *lock);
86 :
87 : /***********************************************************************
88 : ** MACRO: PR_ASSERT_CURRENT_THREAD_OWNS_LOCK
89 : ** DESCRIPTION:
90 : ** If the current thread owns |lock|, this assertion is guaranteed to
91 : ** succeed. Otherwise, the behavior of this function is undefined.
92 : ** INPUTS: PRLock *lock
93 : ** Lock to assert ownership of.
94 : ** OUTPUTS: void
95 : ** RETURN: None
96 : ***********************************************************************/
97 : #if defined(DEBUG) || defined(FORCE_PR_ASSERT)
98 : #define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock) \
99 : PR_AssertCurrentThreadOwnsLock(lock)
100 : #else
101 : #define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock)
102 : #endif
103 :
104 : /* Don't call this function directly. */
105 0 : NSPR_API(void) PR_AssertCurrentThreadOwnsLock(PRLock *lock);
106 :
107 : PR_END_EXTERN_C
108 :
109 : #endif /* prlock_h___ */
|
