• file
• revisions
• annotate
• diff
• comparison
• raw

nsprpub/pr/include/prlock.h@925c144e1f1f (annotated)

nsprpub/pr/include/prlock.h

Fri, 16 Jan 2015 18:13:44 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Fri, 16 Jan 2015 18:13:44 +0100

branch

TOR_BUG_9701

changeset 14

925c144e1f1f

permissions

-rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

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