UTS6710/aps/include/gsl/gl_mutex.h

#ifndef __GSL_MUTEX_H__
#define __GSL_MUTEX_H__

#include "gl_types.h"

/******************************************************************************/
/*!
 * @brief	Create and initialize a mutex for use.
 *
 * @param	szName string identifier for the interrupt.
 * @param	pMutexId Mutex object identifier returned by the API (on success)
 *
 * @return	GL_SUCCESS on success
 * @return	GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_MutexCreate(char *szName, GL_Mutex_t * pMutexId);

/*******************************************************************************************
 * Function:	void GL_MutexCreateRecursive(char *szName, GL_Mutex_t * pMutexId)
 *
 * Parameters:
 *				szName: string identifier for the interrupt. Up to 16 characters.
 * 				pMutexId: Mutex object identifier returned by the API (on success)
 *
 *
 * Returns:		GL_SUCCESS on success
 * 				GL_FAILURE on failure
 *
 * Description:	Create and initialize a mutex with recursive type for use.
 * Restrictions:None
 ******************************************************************************************/
GL_Status_t GL_MutexCreateRecursive(char *szName, GL_Mutex_t * pMutexId);

/******************************************************************************/
/*!
 * @brief	Used to delete a Mutex. Regarding tasks waiting on a deleted Mutex, the behavior depends on the underlying OS; the GSL does not guarantee a default behavior (hence, applications should avoid this scenario). Typically, an error is returned to the waiting tasks.
 *
 * @param	pMutexId Mutex object identifier returned by the API (on success)
 *
 * @return	GL_SUCCESS on success
 * @return	GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_MutexDelete(GL_Mutex_t mutexId);

/******************************************************************************/
/*!
 * @brief	This locks a mutex. If the mutex is not available, the thread should be blocked until the mutex is available or the thread is awaken by a signal The behavior depends on the underlying OS; the GSL does not guarantee a default behavior (hence, applications should avoid this scenario). Typically, an error is returned to the waiting tasks.
 *
 * @param	mutexId Mutex object identifier
 *
 * @return	GL_SUCCESS on success
 * @return	GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR.
 *******************************************************************************/
GL_Status_t GL_MutexLock(GL_Mutex_t mutexId);

/******************************************************************************/
/*!
 * @brief	To lock a mutex. If the mutex is not available, an error is is returned.
 *
 * @param	mutexId Mutex object identifier
 *
 * @return	GL_SUCCESS on success
 * @return	GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR.
 *******************************************************************************/
GL_Status_t GL_MutexTryLock(GL_Mutex_t mutexId);

/******************************************************************************/
/*!
 * @brief	To unlock a mutex. Note that it is undefined behavior to unlock a mutex that is in an unlocked state, or to unlock a mutex that was locked by another thread.
 *
 * @param	mutexId Mutex object identifier
 *
 * @return	GL_SUCCESS on success
 * @return	GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR.
 *******************************************************************************/
GL_Status_t GL_MutexUnlock(GL_Mutex_t mutexId);

#endif // __GL_MUTEX_H__