/*
 * zSyncQueue.h
 * 
 * The Zen API 
 * Copyright (C) 2008-2010 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */ 
#ifndef LMITECH_ZSYNCQUEUE_H_INCLUDED
#define LMITECH_ZSYNCQUEUE_H_INCLUDED

#include <zApi.h>
#include <zApiBegin.h>

typedef zHandle zSyncQueue;     // Represents a thread-synchronized, FIFO queue. 

typedef zStatus(ZAPI_CALL *zSyncQueueDropCallback) (zHandle context, zSyncQueue queue, const void* item); //
//
//  Description:
//      Defines the signature of a callback function to receive queue drop notifications.
//  Arguments:
//      context - User context handle.
//      queue - zSyncQueue object. 
//      item - Pointer to the item that is being dropped. 

ZAPI_EXPORT(zStatus) zSyncQueue_Construct(zSyncQueue* queue, zUIntPtr itemSize, z32u capacity); //
//
//  Description:
//      Constructs a synchronized queue object.
//  Arguments:
//      queue - Destination for the constructed object handle.
//      itemSize - Size, in bytes, of each item in the queue. 
//      capacity - Maximum count of items that can be contained by the queue. 

ZAPI_EXPORT(zStatus) zSyncQueue_SetDropHandler(zSyncQueue queue, zSyncQueueDropCallback onDrop, zHandle context); //
//
//  Description:
//      Registers or unregisters a callback function that is notified when queue items are dropped.
//  Arguments:
//      receiver - zSyncQueue object. 
//      onDrop - Callback function, or zNULL to de-register for callback notification.
//      context - User context handle supplied to the callback function.
//  Remarks: 
//      The drop handler will be called when a queue item is added and capacity is exhausted.  The drop handler
//      can take any necessary actions, such as freeing the item. 

ZAPI_EXPORT(zStatus) zSyncQueue_Destroy(zSyncQueue queue); //
//
//  Description:
//      Destroys the queue object.
//  Arguments:
//      queue - The zSyncQueue object to be destroyed.

ZAPI_EXPORT(zStatus) zSyncQueue_Add(zSyncQueue queue, const void* item); //
//
//  Description:
//      Adds the specified item to the queue; eliminates oldest item if capacity exhausted. 
//  Arguments:
//      queue - zSyncQueue object. 
//      item - Pointer to the object to be copied into the queue. 

ZAPI_EXPORT(zStatus) zSyncQueue_Remove(zSyncQueue queue, void* item, z64u timeout); //
//
//  Description:
//      Blocks until an item can be removed from the queue. 
//  Arguments:
//      queue - zSyncQueue object. 
//      item - Destination for the object to be removed. 
//      timeout - Timeout, in microseconds.
//  Remarks: 
//      This function will return zERROR_TIMEOUT if no items are available 
//      before the specified timeout interval elapses. 

ZAPI_EXPORT(zStatus) zSyncQueue_Item(zSyncQueue queue, z32u index, void* item); //
//
//  Description:
//      Gets the item at the specified offset within the queue. 
//  Arguments:
//      queue - zSyncQueue object. 
//      index - Index of the item to be accessed. 
//      item - Destination for the object that is accessed. 

ZAPI_EXPORT(zUIntPtr) zSyncQueue_ItemSize(zSyncQueue queue); //
//
//  Description:
//      Returns the size of items contained by the queue. 
//  Arguments:
//      queue - zSyncQueue object. 

ZAPI_EXPORT(z32u) zSyncQueue_Count(zSyncQueue queue); //
//
//  Description:
//      Returns the count of items contained by the queue. 
//  Arguments:
//      queue - zSyncQueue object. 

ZAPI_EXPORT(z32u) zSyncQueue_Capacity(zSyncQueue queue); //
//
//  Description:
//      Returns the maximum count of items that can be contained by the queue. 
//  Arguments:
//      queue - zSyncQueue object. 

ZAPI_EXPORT(z64u) zSyncQueue_DropCount(zSyncQueue queue); //
//
//  Description:
//      Returns the number of items that have been dropped due to capacity exhuastion.
//  Arguments:
//      queue - zSyncQueue object. 


#include <zApiEnd.h>

#endif  /* #ifndef LMITECH_ZSYNCQUEUE_H_INCLUDED */
