1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prlock.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,109 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 +** File: prlock.h
1.11 +** Description: API to basic locking functions of NSPR.
1.12 +**
1.13 +**
1.14 +** NSPR provides basic locking mechanisms for thread synchronization. Locks
1.15 +** are lightweight resource contention controls that prevent multiple threads
1.16 +** from accessing something (code/data) simultaneously.
1.17 +**/
1.18 +
1.19 +#ifndef prlock_h___
1.20 +#define prlock_h___
1.21 +
1.22 +#include "prtypes.h"
1.23 +
1.24 +PR_BEGIN_EXTERN_C
1.25 +
1.26 +/**********************************************************************/
1.27 +/************************* TYPES AND CONSTANTS ************************/
1.28 +/**********************************************************************/
1.29 +
1.30 +/*
1.31 + * PRLock --
1.32 + *
1.33 + * NSPR represents the lock as an opaque entity to the client of the
1.34 + * API. All routines operate on a pointer to this opaque entity.
1.35 + */
1.36 +
1.37 +typedef struct PRLock PRLock;
1.38 +
1.39 +/**********************************************************************/
1.40 +/****************************** FUNCTIONS *****************************/
1.41 +/**********************************************************************/
1.42 +
1.43 +/***********************************************************************
1.44 +** FUNCTION: PR_NewLock
1.45 +** DESCRIPTION:
1.46 +** Returns a pointer to a newly created opaque lock object.
1.47 +** INPUTS: void
1.48 +** OUTPUTS: void
1.49 +** RETURN: PRLock*
1.50 +** If the lock can not be created because of resource constraints, NULL
1.51 +** is returned.
1.52 +**
1.53 +***********************************************************************/
1.54 +NSPR_API(PRLock*) PR_NewLock(void);
1.55 +
1.56 +/***********************************************************************
1.57 +** FUNCTION: PR_DestroyLock
1.58 +** DESCRIPTION:
1.59 +** Destroys a given opaque lock object.
1.60 +** INPUTS: PRLock *lock
1.61 +** Lock to be freed.
1.62 +** OUTPUTS: void
1.63 +** RETURN: None
1.64 +***********************************************************************/
1.65 +NSPR_API(void) PR_DestroyLock(PRLock *lock);
1.66 +
1.67 +/***********************************************************************
1.68 +** FUNCTION: PR_Lock
1.69 +** DESCRIPTION:
1.70 +** Lock a lock.
1.71 +** INPUTS: PRLock *lock
1.72 +** Lock to locked.
1.73 +** OUTPUTS: void
1.74 +** RETURN: None
1.75 +***********************************************************************/
1.76 +NSPR_API(void) PR_Lock(PRLock *lock);
1.77 +
1.78 +/***********************************************************************
1.79 +** FUNCTION: PR_Unlock
1.80 +** DESCRIPTION:
1.81 +** Unlock a lock. Unlocking an unlocked lock has undefined results.
1.82 +** INPUTS: PRLock *lock
1.83 +** Lock to unlocked.
1.84 +** OUTPUTS: void
1.85 +** RETURN: PR_STATUS
1.86 +** Returns PR_FAILURE if the caller does not own the lock.
1.87 +***********************************************************************/
1.88 +NSPR_API(PRStatus) PR_Unlock(PRLock *lock);
1.89 +
1.90 +/***********************************************************************
1.91 +** MACRO: PR_ASSERT_CURRENT_THREAD_OWNS_LOCK
1.92 +** DESCRIPTION:
1.93 +** If the current thread owns |lock|, this assertion is guaranteed to
1.94 +** succeed. Otherwise, the behavior of this function is undefined.
1.95 +** INPUTS: PRLock *lock
1.96 +** Lock to assert ownership of.
1.97 +** OUTPUTS: void
1.98 +** RETURN: None
1.99 +***********************************************************************/
1.100 +#if defined(DEBUG) || defined(FORCE_PR_ASSERT)
1.101 +#define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock) \
1.102 + PR_AssertCurrentThreadOwnsLock(lock)
1.103 +#else
1.104 +#define PR_ASSERT_CURRENT_THREAD_OWNS_LOCK(/* PrLock* */ lock)
1.105 +#endif
1.106 +
1.107 +/* Don't call this function directly. */
1.108 +NSPR_API(void) PR_AssertCurrentThreadOwnsLock(PRLock *lock);
1.109 +
1.110 +PR_END_EXTERN_C
1.111 +
1.112 +#endif /* prlock_h___ */
