/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss of reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

#include "coop.h"

/** @addtogroup coop_lock */
/** @{ */

/**
*	Initialises a lock before use.
*
*	Before you can use a lock, you must initialise it. After this function
*	the lock will be ready to use. The function does not suspend the caller.
*
*	@param	lock	Pointer to the lock to initialise
*/

void	BZ_LockInit( BZ_LOCK *lock )
{
	*lock = 255;
}

/**
*	Obtain a lock.
*
*	If the lock is available, then the function takes it and returns
*	immediately. Otherwise, it will suspend the caller until the lock
*	becomes free. If the lock is already owned by the caller, then the
*	function returns immediately.
*
*	@param	lock	Pointer to the lock
*
*	@retval	0		The lock is already owned by the caller
*	@retval	1		The lock was free and now is owned by the caller
*
*	@attention
*		This function must not be called from an interrupt. It you do
*		that, the system will crash.
*/

int		BZ_LockObtain( BZ_LOCK *lock )
{
int		retv;

	while ( ( retv = BZ_LockAttempt( lock ) ) < 0 )

		BZ_EventWait( BZ_EVENT_LOCK );

	return( retv );
}

/**
*	Release a lock.
*
*	The caller, who must be the current owner of the lock, releases
*	the lock. This call does not suspend the caller.
*
*	@param	lock	Pointer to the lock
*
*	@retval	BZ_NOT_OWNER	The caller did not own the lock
*	@retval	0				The lock was released.
*
*	@attention
*		This function must not be called from an interrupt.
*/

int		BZ_LockRelease( BZ_LOCK *lock )
{
	if ( *lock != _bz_stat.self ) return( BZ_NOT_OWNER );
	*lock = 255;
	_bz_EventPost( 255, BZ_EVENT_LOCK );
	return( 0 );
}

/**
*	Attempt to obtain a lock.
*
*	This function tries to obtain the lock, but does not wait if
*	it is not available. It does not suspend the caller.
*
*	@param	lock	Pointer to the lock
*
*	@retval	0			The lock is already owned by the caller
*	@retval	1			The lock was free and now is owned by the caller
*	@retval	BZ_IN_USE	The lock is owned by an other thread
*
*	@attention
*		This function must not be called from an interrupt.
*/

int		BZ_LockAttempt( BZ_LOCK *lock )
{
	if ( *lock == _bz_stat.self ) return( 0 );
	if ( *lock != 255 ) return( BZ_IN_USE );
	*lock = _bz_stat.self;
	return( +1 );
}

/** @} */

