/***********************************************************************
Filename   : rvqueue.h
Description: rvqueue 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: Queue}
	{superpackage: CBase}
	{include: rvqueue.h}
	{description:	
		{p: This module provides functions for creating and manipulating queues. These
			queues are completely thread safe and support multiple threads operating
			a single queue simultaneously.}
	}
}
$*/
#ifndef RV_QUEUE_H
#define RV_QUEUE_H

#include "rvcbase.h"
#include "rvlock.h"
#include "rvsemaphore.h"
#include "rvmemory.h"

/* Error checks to make sure configuration has been done properly */
#if !defined(RV_QUEUE_TYPE) || ((RV_QUEUE_TYPE != RV_QUEUE_STANDARD))
#error RV_QUEUE_TYPE not set properly
#endif
/* End of configuration error checks */

/* Module specific error codes (-512..-1023). See rverror.h for more details */
#define RV_QUEUE_ERROR_EMPTY   -512 /* queue is empty */
#define RV_QUEUE_ERROR_FULL    -513 /* queue is full */
#define RV_QUEUE_ERROR_STOPPED -514 /* queue is stopped */

/* priority for RvQueueSend, URGENT puts item at front of queue */
#define RV_QUEUE_SEND_NORMAL RvIntConst(0)
#define RV_QUEUE_SEND_URGENT RvIntConst(1)

/* Constants for indicating if queue functions should block. */
#define RV_QUEUE_WAIT RV_TRUE
#define RV_QUEUE_NOWAIT RV_FALSE

/*$
{type:
	{name: RvQueue}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:	
		{p: A queue object.}
	}
}
$*/
typedef struct {
	RvSize_t size;        /* Maximum number of items in queue */
	RvSize_t curitems;    /* current number of items in queue */
	RvSize_t itemsize;    /* size of each item in queue */
	RvLock lock;          /* lock on queue data structure */
	RvSemaphore emptysem; /* semaphore to block tasks waiting due to empty queue */
	RvSemaphore fullsem;  /* semaphore to block tasks waiting due to full queue */
	RvSize_t waitempty;   /* number of tasks waiting on "emptysem" */
	RvSize_t waitfull;    /* number of tasks waiting on "fullsem" */
	RvSize_t notifyempty; /* Number of tasks waiting on "emptysem" told to continue */
	RvSize_t notifyfull;  /* Number of tasks waiting on "fullsem" told to continue */
	void *bufstart;       /* start of queue storage, first physical item */
	void *bufend;         /* end of queue storage, last physical item */
	void *firstitem;      /* current logical item at front of queue */
	void *lastitem;       /* current logical item at end of queue */
	RvBool stopped;       /* set to RV_TRUE when queue has been stopped */
} RvQueue;

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

/* Prototypes: See documentation blocks below for details. */
RvStatus RvQueueInit(void);
RvStatus RvQueueEnd(void);
RVCOREAPI RvStatus RVCALLCONV RvQueueConstruct(RvQueue *queue, RvSize_t numitems, RvSize_t itemsize, RvMemory *bufmem);
RVCOREAPI RvStatus RVCALLCONV RvQueueDestruct(RvQueue *queue);
RVCOREAPI RvStatus RVCALLCONV RvQueueReceive(RvQueue *queue, void *buf, RvSize_t bufsize, RvBool wait);
RVCOREAPI RvStatus RVCALLCONV RvQueueSend(RvQueue *queue, void *buf, RvSize_t bufsize, RvInt priority, RvBool wait);
RVCOREAPI RvStatus RVCALLCONV RvQueueStop(RvQueue *queue);
RVCOREAPI RvStatus RVCALLCONV RvQueueClear(RvQueue *queue);
RvBool RvQueueIsStopped(RvQueue *queue);
RvSize_t RvQueueSize(RvQueue *queue);
RvSize_t RvQueueItems(RvQueue *queue);

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

#if defined(__cplusplus)
}
#endif 

/* Function Documentation */
/*$
{function scope="protected":
	{name: RvQueueInit}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Initializes the Queue module. Must be called once (and
			only once) before any other functions in the module are called.}
	}
	{proto: RvStatus RvQueueInit(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function scope="protected":
	{name: RvQueueEnd}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Shuts down the Queue module. Must be called once (and
			only once) when no further calls to this module will be made.}
	}
	{proto: RvStatus RvQueueEnd(void); }
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvQueueConstruct}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Constructs a queue object based on the parameters passed in.}
	}
	{proto: RvStatus RvQueueConstruct(RvQueue *queue, RvSize_t numitems, RvSize_t *itemsize, RvMemory *bufmem);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to be constructed.}}
		{param: {n: numitems} {d: Number of items that the queue should be able to hold.}}
		{param: {n: itemsize} {d: Maximum size of each item that will put put into the queue.}}
		{param: {n: bufmem} {d: Memory region to allocate queue memeory from (NULL = default region).}}
	}
	{returns: RV_OK if successful otherwise an error code.}
}
$*/
/*$
{function:
	{name: RvQueueDestruct}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Destructs a queue.}
	}
	{proto: RvStatus RvQueueDestruct(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to be Destructed.}}
	}
	{returns: RV_OK if successful otherwise an error code.}
	{notes:
		{note:  All items in the queue are lost when the queue is destructed.}
		{note:  Insure that no threads are operating on the queue when it is
				destructing since not all operating systems handle the situation
				gracefully.}
		}
}
$*/
/*$
{function:
	{name: RvQueueReceive}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Gets an item from the front of a queue.}
	}
	{proto: RvStatus RvQueueReceive(RvQueue *queue, void *buf, RvSize_t bufsize, RvBool wait);}
	{params:
		{param: {n: queue}  {d: Pointer to queue object to get item from.}}
		{param: {n: buf}    {d: Pointer to buffer that item will be copied to.}}
		{param: {n: bufsize} {d: Size of the buffer that buf points to.}}
		{param: {n: wait}   {d: Set to RV_QUEUE_WAIT if thread should wait until item is available.
								If set to RV_QUEUE_NOWAIT, RV_QUEUE_ERROR_EMPTY will be returned if
								no item is available.}}
	}
	{returns:   RV_OK if successful otherwise an error code. An error code of RV_QUEUE_ERROR_STOPPED
				indicates that the queue has been permanently stopped and there are no more items
				available in the queue.}
	{notes:
		{note:  A thread waiting for data on a queue will be resumed and return
				RV_QUEUE_ERROR_STOPPED if the queue is stopped.}
		{note:  If the buffer is smaller than the item in the queue, the data
				copied into the buffer will be truncated.}
	}
}
$*/
/*$
{function:
	{name: RvQueueSend}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Puts an item into a queue.}
	}
	{proto: RvStatus RvQueueSend(RvQueue *queue, void *buf, RvSize_t bufsize, RvInt priority, RvBool wait);}
	{params:
		{param: {n: queue}      {d: Pointer to queue object where item should be placed.}}
		{param: {n: buf}        {d: Pointer to buffer that contains the item.}}
		{param: {n: bufsize}    {d: Size of the item that buf points to.}}
		{param: {n: priority}   {d: Set to RV_QUEUE_SEND_NORMAL to put item at the end of the queue.
									Set to RV_QUEUE_SEND_URGENT to put the item at the front
									of the queue.}}
		{param: {n: wait}       {d: Set to RV_QUEUE_WAIT if thread should wait until space is available
									in the queue for the item. If set to RV_QUEUE_NOWAIT,
									RV_QUEUE_ERROR_FULL will be returned if there is no space in the queue.}}
	}
	{returns:   RV_OK if successful otherwise an error code. An error code of RV_QUEUE_ERROR_STOPPED
				indicates that the queue has been permanently stopped and no more items are allowed
				to be put in the queue.}
	{notes:
		{note:  A thread waiting to put data on a queue will be resumed and return
				RV_QUEUE_ERROR_STOPPED if the queue is stopped.}
	}
}
$*/
/*$
{function:
	{name: RvQueueStop}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Permanently stops a queue. No more items will be allowed to be put on the queue.
			Threads waiting to get items from the queue or waiting to put items onto the queue
			will be resumed (and return with an error code indicating that the queue has been
			stopped). Items already on the queue will still be available.}
	}
	{proto: RvStatus RvQueueStop(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to be stopped.}}
	}
	{returns:   RV_OK if successful otherwise an error code.}
	{notes:
		{note:  When a queue is stopped it is permanent, there is no way to undo it.}
	}
}
$*/
/*$
{function:
	{name: RvQueueClear}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Clears all items from a queue.}
	}
	{proto: RvStatus RvQueueClear(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to be cleared.}}
	}
	{returns:   RV_OK if successful otherwise an error code.}
	{notes:
		{note:  Stopped queues may be cleared.}
	}
}
$*/
/*$
{function:
	{name: RvQueueIsStopped}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Checks to see if a queue has been stopped.}
	}
	{proto: RvBool RvQueueIsStopped(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to check.}}
	}
	{returns: Returns RV_TRUE if the queue has been stopped, RV_FALSE otherwise.}
}
$*/
/*$
{function:
	{name: RvQueueSize}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Finds out the size of the queue.}
	}
	{proto: RvSize_t RvQueueSize(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to check.}}
	}
	{returns: The maximum number of items that the queue can hold.}
}
$*/
/*$
{function:
	{name: RvQueueItems}
	{superpackage: Queue}
	{include: rvqueue.h}
	{description:
		{p: Finds out the number of items currently on the queue.}
	}
	{proto: RvSize_t RvQueueItems(RvQueue *queue);}
	{params:
		{param: {n: queue} {d: Pointer to queue object to check.}}
	}
	{returns: The current number of items on the queue.}
}
$*/

#endif