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
21PR_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
34typedef 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***********************************************************************/
51NSPR_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***********************************************************************/
62NSPR_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***********************************************************************/
73NSPR_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***********************************************************************/
85NSPR_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. */
105NSPR_API(void) PR_AssertCurrentThreadOwnsLock(PRLock *lock);
106
107PR_END_EXTERN_C
108
109#endif /* prlock_h___ */
110

source code of include/nspr/prlock.h