rvsemaphore.h

基于h323协议的软phone

/***********************************************************************
Filename   : rvsemaphore.h
Description: rvsemaphore 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: Semaphore}
    {superpackage: CCore}
    {include: rvsemaphore.h}
    {description:
        {p: This module provides semaphore functions.}
    }
}
$*/
#ifndef RV_SEMAPHORE_H
#define RV_SEMAPHORE_H

#include "rvccore.h"

#if !defined(RV_SEMAPHORE_TYPE) || ((RV_SEMAPHORE_TYPE != RV_SEMAPHORE_POSIX) && \
    (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_VXWORKS) && (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_PSOS) && \
    (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_OSE) && (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_NUCLEUS) && \
    (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_WIN32) && (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_NONE))
#error RV_SEMAPHORE_TYPE not set properly
#endif

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

/*$
{type:
    {name: RvSemaphore}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: A counting semaphore object.}
    }
}
$*/
/*$
{type:
    {name: RvSemaphoreAttr}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: OS specific attributes and options used for semaphore. See definitions in rvsemaphore.h
            along with the default values in rvccoreconfig.h for more information.}
    }
}
$*/
/* Get include files and define RvSemaphore and RvSemaphoreAttr for each OS */
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_POSIX)
#include <semaphore.h>
typedef sem_t RvSemaphore;
typedef int RvSemaphoreAttr; /* 0 = not shared, otherwise shared */
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_VXWORKS)
#include <vxworks.h>
#include <semLib.h>
typedef SEM_ID RvSemaphore;
typedef int RvSemaphoreAttr; /* options to semCCreate */
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_PSOS)
#include <psos.h>
typedef unsigned long RvSemaphore;
typedef unsigned long RvSemaphoreAttr; /* flags to sm_create (Don't set BOUNDED/UNBOUNDED). */
#if (RV_OS_VERSION == RV_OS_PSOS_2_0)
#define SM_UNBOUNDED 0
#endif
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_OSE)
#include <ose.h>
typedef SEMAPHORE *RvSemaphore;
typedef int RvSemaphoreAttr; /* not used */
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_NUCLEUS)
#include <nucleus.h>
typedef NU_SEMAPHORE RvSemaphore;
typedef OPTION RvSemaphoreAttr; /* suspend_type */
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_WIN32)
#include <windows.h>
typedef HANDLE RvSemaphore;
typedef int RvSemaphoreAttr; /* not used */
#endif
#if (RV_SEMAPHORE_TYPE == RV_SEMAPHORE_NONE)
typedef RvInt RvSemaphore;     /* Dummy types, used to prevent warnings. */
typedef RvInt RvSemaphoreAttr; /* not used */
#endif

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

/* Prototypes and macros */
RvStatus RvSemaphoreInit(void);
RvStatus RvSemaphoreEnd(void);
#if (RV_SEMAPHORE_TYPE != RV_SEMAPHORE_NONE)
RvStatus RvSemaphoreConstruct(RvSemaphore *sema, RvUint32 startcount);
RvStatus RvSemaphoreDestruct(RvSemaphore *sema);
RvStatus RvSemaphorePost(RvSemaphore *sema);
RvStatus RvSemaphoreWait(RvSemaphore *sema);
RvStatus RvSemaphoreSetAttr(RvSemaphoreAttr *attr);
#else
/* If none is set then none of these functions do anything */
#define RvSemaphoreConstruct(_s, _c) (*(_s) = RV_OK)
#define RvSemaphoreDestruct(_s) (*(_s) = RV_OK)
#define RvSemaphorePost(_s) (*(_s) = RV_OK)
#define RvSemaphoreWait(_s) (*(_s) = RV_OK)
#define RvSemaphoreSetAttr(_s) (*(_s) = RV_OK)
#endif

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

#if defined(__cplusplus)
}
#endif

/* Function Documentation */
/*$
{function scope="protected":
    {name: RvSemaphoreInit}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Initializes the Semaphore module. Must be called once (and
            only once) before any other functions in the module are called.}
    }
    {proto: RvStatus RvSemaphoreInit(void);}
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
    {name: RvSemaphoreEnd}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Shuts down the Semaphore module. Must be called once (and
            only once) when no further calls to this module will be made.}
    }
    {proto: RvStatus RvSemaphoreEnd(void);}
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
    {name: RvSemaphoreConstruct}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Creates a counting semaphore object.}
    }
    {proto: RvStatus RvSemaphoreConstruct(RvSemaphore *sema, RvUint32 startcount);}
    {params:
        {param: {n: sema} {d: Pointer to lock object to be constructed.}}
        {param: {n: statcount} {d: Initial value of the semaphore.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note: The maximum value of a sempahore is OS and architecture dependent.}
    }
}
$*/
/*$
{function:
    {name: RvSemaphoreDestruct}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Destroys a counting semaphore object.}
    }
    {proto: RvStatus RvSemaphoreDestruct(RvSemaphore *sema);}
    {params:
        {param: {n: sema}  {d: Pointer to semaphore object to be destructed.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note: Never destroy a semaphore object which has a thread suspended on it.}
    }
}
$*/
/*$
{function:
    {name: RvSemaphorePost}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Increments the semaphore.}
    }
    {proto: RvStatus RvSemaphorePost(RvSemaphore *sema);}
    {params:
        {param: {n: sema}  {d: Pointer to semaphore object to be incremented.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
    {notes:
        {note: The maximum value of a sempahore is OS and architecture dependent.}
    }
}
$*/
/*$
{function:
    {name: RvSemaphoreWait}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Decrements a semaphore. If the semaphore is 0, it will suspend the calling task until it can.}
    }
    {proto: RvStatus RvSemaphoreWait(RvSemaphore *sema);}
    {params:
        {param: {n: sema}  {d: Pointer to semaphore object to be decremented.}}
    }
    {returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
    {name: RvSemaphoreSetAttr}
    {superpackage: Semaphore}
    {include: rvsemaphore.h}
    {description:
        {p: Sets the options and attributes to be used when creating and using semaphore objects.}
    }
    {proto: RvStatus RvSemaphoreSetAttr(RvSemaphoreAttr *attr);}
    {params:
        {param: {n: attr}  {d: Pointer to OS speicific semaphore 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 rvsemaphore functions.}
        {note: These attributes are global and will effect all semaphore functions called thereafter.}
        {note: The default values for these attributes are set in rvccoreconfig.h.}
    }
}
$*/

#endif