/***********************************************************************
Filename   : rvmutex.h
Description: rvmutex header file
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
	{name: Mutex}
	{superpackage: CCore}
	{include: rvmutex.h}
	{description:	
		{p: This module provides recursive locking functions to use specifically
			for locking code sections.}
	}
}
$*/
#ifndef RV_MUTEX_H
#define RV_MUTEX_H

#include "rvccore.h"

#if !defined(RV_MUTEX_TYPE) || ((RV_MUTEX_TYPE != RV_MUTEX_SOLARIS) && \
    (RV_MUTEX_TYPE != RV_MUTEX_LINUX) && (RV_MUTEX_TYPE != RV_MUTEX_VXWORKS) && \
    (RV_MUTEX_TYPE != RV_MUTEX_PSOS) && (RV_MUTEX_TYPE != RV_MUTEX_WIN32_MUTEX) && \
    (RV_MUTEX_TYPE != RV_MUTEX_WIN32_CRITICAL) && (RV_MUTEX_TYPE != RV_MUTEX_MANUAL) && \
    (RV_MUTEX_TYPE != RV_MUTEX_NONE))
#error RV_MUTEX_TYPE not set properly
#endif

#if !defined(RV_MUTEX_ATTRIBUTE_DEFAULT)
#error RV_MUTEX_ATTRIBUTE_DEFAULT not set properly
#endif

/*$
{type:
	{name: RvMutex}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:	
		{p: A recursive mutex object.}
	}
}
$*/
/*$
{type:
	{name: RvMutexAttr}
	{superpackage: Mutex}
	{include: rvlock.h}
	{description:	
		{p: OS specific attributes and options used for mutexes. See definitions in rvmutex.h
			along with the default values in rvccoreconfig.h for more information.}
	}
}
$*/
/* Get include files and define RvMutex and RvMutexAttr for each OS */
#if (RV_MUTEX_TYPE == RV_MUTEX_SOLARIS) || (RV_MUTEX_TYPE == RV_MUTEX_LINUX)
/* They're both posix, but they're not exactly the same, so we need 2 settings */
#include <pthread.h>
typedef pthread_mutex_t RvMutex;
typedef struct {
	/* These correspond to attributes in the pthread_mutexattr struct that we let users set */
	int pshared;  /* used only by Solaris */
	int protocol; /* used only by Solaris */
} RvMutexAttr;
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_VXWORKS)
#include <vxworks.h>
#include <semLib.h>
typedef SEM_ID RvMutex;
typedef int RvMutexAttr;  /* options to semMCreate */
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_PSOS)
#include <psos.h>
typedef unsigned long RvMutex;
typedef unsigned long RvMutexAttr; /* flags to mu_create (Don't set RECURSIVE/NORECURSIVE) */
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_WIN32_MUTEX)
#include <windows.h>
typedef HANDLE RvMutex;
typedef int RvMutexAttr; /* not used */
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_WIN32_CRITICAL)
#include <windows.h>
typedef CRITICAL_SECTION RvMutex;
typedef DWORD RvMutexAttr; /* spin count (use only on Win2000 and newer) */
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_MANUAL)
#include "rvsemaphore.h"
#include "rvthread.h"

typedef struct {
	RvSemaphore handle;
	RvSemaphore lock;
	RvThreadId owner;
	RvUint32 count;
	RvUint32 waiters;
} RvMutex;
typedef int RvMutexAttr; /* not used, any semaphore attributes will apply */
#endif
#if (RV_MUTEX_TYPE == RV_MUTEX_NONE)
typedef RvInt RvMutex;     /* Dummy types, used to prevent warnings. */
typedef RvInt RvMutexAttr; /* not used */
#endif

#if defined(__cplusplus)
extern "C" {
#endif 

/* Prototypes: See documentation blocks below for details. */
RvStatus RvMutexInit(void);
RvStatus RvMutexEnd(void);
#if (RV_MUTEX_TYPE != RV_MUTEX_NONE)
RVCOREAPI
RvStatus RVCALLCONV RvMutexConstruct(RvMutex *mu);
RVCOREAPI
RvStatus RVCALLCONV RvMutexDestruct(RvMutex *mu);
RVCOREAPI
RvStatus RVCALLCONV RvMutexLock(RvMutex *mu);
RVCOREAPI
RvStatus RVCALLCONV RvMutexUnlock(RvMutex *mu);
RvStatus RvMutexSetAttr(RvMutexAttr *attr);
#else
/* If none is set then none of these functions do anything */
#define RvMutexConstruct(_m) (*(_m) = RV_OK)
#define RvMutexDestruct(_m) (*(_m) = RV_OK)
#define RvMutexLock(_m) (*(_m) = RV_OK)
#define RvMutexUnlock(_m) (*(_m) = RV_OK)
#define RvMutexSetAttr(_m) (*(_m) = RV_OK)
#endif

#if defined(RV_TEST_CODE)
void RvMutexTest(void);
#endif /* RV_TEST_CODE */

#if defined(__cplusplus)
}
#endif 

/* Function Documentation */
/*$
{function scope="protected":
	{name: RvMutexInit}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Initializes the Mutex module. Must be called once (and
			only once) before any other functions in the module are called.}
	}
	{proto: RvStatus RvMutexInit(void);}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
	{name: RvMutexEnd}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Shuts down the Mutex module. Must be called once (and
			only once) when no further calls to this module will be made.}
	}
	{proto: RvStatus RvMutexEnd(void);}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMutexConstruct}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Creates a recursive mutex object.}
	}
	{proto: RvStatus RvMutexConstruct(RvLock *mu);}
	{params:
		{param: {n: mu}  {d: Pointer to mutex object to be constructed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMutexDestruct}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Destroys a recursive mutex object.}
	}
	{proto: RvStatus RvMutexDestruct(RvMutex *mu);}
	{params:
		{param: {n: mu}  {d: Pointer to recursive mutex object to be destructed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note: Never destroy a mutex object which has a thread suspended on it.}
	}
}
$*/
/*$
{function:
	{name: RvMutexLock}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Aquires a recursive muctex. Will suspend the calling task until the mutex is available.}
	}
	{proto: RvStatus RvMutexLock(RvMutex *mu);}
	{params:
		{param: {n: mu}  {d: Pointer to mutex object to be aquired.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMutexUnlock}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Unlocks a recursive mutex.}
	}
	{proto: RvStatus RvMutexUnlock(RvMutex *mu);}
	{params:
		{param: {n: mu}  {d: Pointer to mutex object to be unlocked.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvMutexSetAttr}
	{superpackage: Mutex}
	{include: rvmutex.h}
	{description:
		{p: Sets the options and attributes to be used when creating and using mutex objects.}
	}
	{proto: RvStatus RvMutexSetAttr(RvLockAttr *attr);}
	{params:
		{param: {n: attr}  {d: Pointer to OS speicific mutex attributes to begin using.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note: Non-reentrant function. Do not call when other threads may be calling rvmutex functions.}
		{note: These attributes are global and will effect all mutex functions called thereafter.}
		{note: The default values for these attributes are set in rvccoreconfig.h.}
	}
}
$*/

#endif