Lock Objects
[Operating System Dependent Functionality.]

Functions
pj_status_t	pj_lock_create_simple_mutex (pj_pool_t *pool, const char *name, pj_lock_t **lock)
pj_status_t	pj_lock_create_recursive_mutex (pj_pool_t *pool, const char *name, pj_lock_t **lock)
pj_status_t	pj_lock_create_null_mutex (pj_pool_t *pool, const char *name, pj_lock_t **lock)
pj_status_t	pj_lock_create_semaphore (pj_pool_t *pool, const char *name, unsigned initial, unsigned max, pj_lock_t **lock)
pj_status_t	pj_lock_acquire (pj_lock_t *lock)
pj_status_t	pj_lock_tryacquire (pj_lock_t *lock)
pj_status_t	pj_lock_release (pj_lock_t *lock)
pj_status_t	pj_lock_destroy (pj_lock_t *lock)

---

Detailed Description

Lock Objects are higher abstraction for different lock mechanisms. It offers the same API for manipulating different lock types (e.g. mutex, semaphores, or null locks). Because Lock Objects have the same API for different types of lock implementation, it can be passed around in function arguments. As the result, it can be used to control locking policy for a particular feature.

---

Function Documentation

pj_status_t pj_lock_acquire

(

pj_lock_t *

lock

)

Acquire lock on the specified lock object.

Parameters:

lock

The lock object.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_create_null_mutex	(	pj_pool_t *	pool,
		const char *	name,
		pj_lock_t **	lock
	)

Create NULL mutex. A NULL mutex doesn't actually have any synchronization object attached to it.

Parameters:

	pool	Memory pool.
	name	Lock object's name.
	lock	Pointer to store the returned handle.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_create_recursive_mutex	(	pj_pool_t *	pool,
		const char *	name,
		pj_lock_t **	lock
	)

Create recursive mutex lock object.

Parameters:

	pool	Memory pool.
	name	Lock object's name.
	lock	Pointer to store the returned handle.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_create_semaphore	(	pj_pool_t *	pool,
		const char *	name,
		unsigned	initial,
		unsigned	max,
		pj_lock_t **	lock
	)

Create semaphore lock object.

Parameters:

	pool	Memory pool.
	name	Lock object's name.
	initial	Initial value of the semaphore.
	max	Maximum value of the semaphore.
	lock	Pointer to store the returned handle.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_create_simple_mutex	(	pj_pool_t *	pool,
		const char *	name,
		pj_lock_t **	lock
	)

Create simple, non recursive mutex lock object.

Parameters:

	pool	Memory pool.
	name	Lock object's name.
	lock	Pointer to store the returned handle.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_destroy

(

pj_lock_t *

lock

)

Destroy the lock object.

Parameters:

lock

The lock object.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_release

(

pj_lock_t *

lock

)

Release lock on the specified lock object.

Parameters:

lock

The lock object.

Returns:

PJ_SUCCESS or the appropriate error code.

pj_status_t pj_lock_tryacquire

(

pj_lock_t *

lock

)

Try to acquire lock on the specified lock object.

Parameters:

lock

The lock object.

Returns:

PJ_SUCCESS or the appropriate error code.