#ifndef _SIMPLE_QUEUE_H
#define _SIMPLE_QUEUE_H 1
/*++
Copyright (c) 1996 Microsoft Corporation
Module Name:
simpleq.h
Abstract:
Simple non-blocking queue, that allows
multiple concurrent data providers
and singe data consumer
Author:
GorN 9-Feb-1999
Revision History:
--*/
#define COUNT_DROPPED_PACKETS 1 // Enable dropped packet counting
// The queue can store blocks of variable sizes
// each block is prefixed by this structure
typedef struct _SIMPLEQUEUE_BLOCK_HEADER
{
DWORD PayloadSize; // this is the size of the block
// as it was passed to us by the client
}
SIMPLEQUEUE_BLOCK_HEADER, *PSIMPLEQUEUE_BLOCK_HEADER;
#define SQB_ALIGNMENT ( sizeof(DWORD) )
#define SQB_INFLATE_SIZE( size )( (size + SQB_ALIGNMENT - 1) & ~(SQB_ALIGNMENT - 1) )
#define SQB_PAYLOADSIZE_TO_BLOCKSIZE( size )( SQB_INFLATE_SIZE(size + sizeof(SIMPLEQUEUE_BLOCK_HEADER)) )
#define SQB_HEADER( ptr ) ( (PSIMPLEQUEUE_BLOCK_HEADER)(ptr) )
#define SQB_PAYLOADSIZE( ptr ) ( SQB_HEADER(ptr)->PayloadSize )
#define SQB_BLOCKSIZE( ptr ) ( SQB_PAYLOADSIZE_TO_BLOCKSIZE( SQB_PAYLOADSIZE( ptr ) ) )
#define SQB_NEXTBLOCK( ptr ) ( (PVOID)( (PUCHAR)(ptr) + SQB_BLOCKSIZE( ptr ) ) )
#define SQB_PAYLOAD( ptr ) ( (PVOID)(SQB_HEADER(ptr) + 1) )
typedef struct _SIMPLEQUEUE *PSIMPLEQUEUE;
// The following function will be called if there are dropped data and
// the last time we reported dropped data was NotifyInterval
// or more seconds before.
typedef void (*DROPPED_DATA_NOTIFY) (
IN PWCHAR QueueName,
IN DWORD DroppedDataCount,
IN DWORD DroppedDataSize);
// The following function will be called if there are data available
// in the queue. It will not be called again until
// Read/CompleteRead operations empty the queue.
typedef void (*DATA_AVAILABLE_CALLBACK)(
IN PSIMPLEQUEUE q);
DWORD SimpleQueueInitialize(
IN OUT PSIMPLEQUEUE q,
IN DWORD cbSize,
IN PWCHAR Name,
IN DATA_AVAILABLE_CALLBACK DataAvailableCallback,
IN DROPPED_DATA_NOTIFY DroppedDataNotifyCallback,
IN DWORD NotifyInterval // in seconds //
);
/*++
Routine Description:
Initializes a queue
Arguments:
q - a queue to be initialized
cbSize - size of the queue in bytes
Name - Name of the queue. It will be supplied to DroppedDataNotifyCallback
DataAvailableCallback - This function will be called if there are data available
in the queue. This function will not be called again until
Read/CompleteRead operations empty the queue.
DroppedDataNotifyCallback - This function will be called if there are dropped data and
the last time we reported dropped data was NotifyInterval
or more seconds before.
NotifyInterval - We will not report dropped data unless it has been longer
than NotifyInterval seconds since the last report
Return Value:
ERROR_SUCCESS - success
error code - called failed
*/
VOID
SimpleQueueDelete(
IN PSIMPLEQUEUE q
);
/*++
Routine Description:
Destroys a queue
Arguments:
q - a queue to be destroyed
Return Value:
None
Comments:
This routine will destroy queue's CriticalSection
and deallocate queue's memory. It is the responsibility of
the caller to guarantee that nobody will be using the queue
after this function is called
*/
BOOL
SimpleQueueTryAdd(
IN PSIMPLEQUEUE q,
IN DWORD PayloadSize,
IN PVOID Payload
);
/*++
Routine Description:
Tries to add data in a queue
Arguments:
q - a queue
PayloadSise - size of the chunk to be added to a queue
Payload - pointer to a buffer that countains data to be added
Return Value:
TRUE - if the data were put into the queue successfully
FALSE - otherwise
Comments:
DataAvailableCallback will be called
if there are data available. DataAvailableCallback will not be called
during subsequent add requests until Read/CompleteRead
operations empty the queue.
*/
BOOL
SimpleQueueReadAll(
IN PSIMPLEQUEUE q,
OUT PVOID* begin,
OUT PVOID* end
);
/*++
Routine Description:
Allows to read all available blocks
Arguments:
q - a queue
begin - receives a pointer to the first queue block
end - receives a pointer past the end of the last queue block
Return Value:
TRUE - if we get at least one block
FALSE - if the queue is empty
Comments:
This function not always give you ALL available blocks in the
queue. It gives you all blocks up until the hard end of the queue buffer or
the writing head of the queue, whatever is smaller.
If the function returns success, it guarantees that begin < end.
When you finished processing of the data, you need to call
SimpleQueueReadComplete function.
You can walk over these block using SQB_NEXTBLOCK macro.
*/
BOOL
SimpleQueueReadOne(
IN PSIMPLEQUEUE q,
OUT PVOID* begin,
OUT PVOID* end
);
/*++
Routine Description:
Allows to read a single block of data
Arguments:
q - a queue
begin - receives a pointer to the beginning of the first available queue block
end - receives a pointer past the end of this block
Return Value:
TRUE - success
FALSE - if the queue is empty
Comments:
When you finished processing of the data, you need to call
SimpleQueueReadComplete function.
*/
BOOL
SimpleQueueReadComplete(
IN PSIMPLEQUEUE q,
IN PVOID newtail
);
/*++
Routine Description:
Use this function to signal that the block of data was
consumed
Arguments:
q - a queue
end - receives a pointer past the end of the last consumed block.
Usually this is a value returned by the PVOID end parameter of
ReadOne and ReadAll
Return Value:
TRUE - There are more data
FALSE - if the queue is empty
Important!!!
If the result of this function is TRUE, the caller should consume the data
using ReadOne or ReadAll functions followed by the calls
to ReadComplete until it returns FALSE.
Otherwise, no futher DataAvailable notifications will be produced bu
SimpleQueueTryAdd
*/
#ifdef COUNT_DROPPED_PACKETS
VOID
CheckForDroppedData(
IN PSIMPLEQUEUE q,
IN BOOL Now
);
/*++
Routine Description:
This function checks whether there were
some data dropped and if the time is right,
calls DropNotifyCallback function.
Arguments:
q - a queue
Now - If TRUE, than DropNotifyCallback will be called
immediately if there are dropped data.
If FALSE, DropNotifyCallback will be called
only if it is more then DroppedNotifyInterval
seconds elapsed, since the last time we called
DropNotifyCallback
Return Value:
None
*/
#else
#define CheckForDroppedData(x,y)
#endif
typedef struct _SIMPLEQUEUE {
CRITICAL_SECTION Lock;
PWCHAR Name; // arbitrary string
PUCHAR Begin; // queue buffer start
PUCHAR End; // queue buffer end
PUCHAR Head; // writing head
PUCHAR Tail; // consuming end
PUCHAR Wrap; // wrap == 0, if tail < head
// otherwise if it points past the end of
// the last block before queue buffer end
BOOL Empty; // This flag is properly maintained by the queue,
// but not required for the queue to operate
// Can be removed if nobody needs it
BOOL Enabled; // Add operation to the queue will fail
// if the enabled flag is not set
UINT32 ReadInProgress; // DataAvailableCallback notification
// was issued and processing is not
// complete.
//
// This flag is reset by ReadComplete
// when there are no more data
DATA_AVAILABLE_CALLBACK DataAvailableCallback;
#ifdef COUNT_DROPPED_PACKETS
ULARGE_INTEGER NextDroppedDataNotify;
DROPPED_DATA_NOTIFY DroppedDataNotifyCallback;
ULARGE_INTEGER DroppedDataNotifyInterval;
DWORD DroppedDataCount; // These two variable are reset each time
DWORD DroppedDataSize; // we call DroppedDataNotifyCallback
#endif
//
} SIMPLEQUEUE;
#endif