/*++
Copyright (c) 1997-1999 Microsoft Corporation
Module Name:
queue.c
Abstract:
Generic efficient queue package.
Author:
John Vert (jvert) 12-Jan-1996
Revision History:
David Orbits (davidor) 23-Apr-1997
Added command packet routines.
Added interlocked list routines.
Introduction
A striped queue is really just a list of queues that are managed as a single
queue. When a caller request a queue entry, the first entry for the queue at
the head of the list is returned and that queue is moved to the tail of the
list to prevent starvation of the other queues on the list. Callers sleep when
none of the queues have entries. The caller must be ready to accept an entry
from any queue. Striped queues allow a caller to serialize access to a
sub-queue.
Structures
The same structure is used for both the queue and the controlling queue.
A controlling queue plus its component queues are termed a striped queue.
There is no striped queue structure. The struct contains the following:
- critical section for locking
- List head for entries
- Address of the controlling queue
- List head for Full queues
- List head for Empty queues
- List head for Idled queues
- Count of the number of entries on a queue
- Count of the number of entries on all controlled queues
Initializing
A non-striped (regular) queue is created with:
FrsRtlInitializeQueue(Queue, Queue)
A striped queue controlled by ControlQueue and composed of QueueA and QueueB
is created with:
FrsRtlInitializeQueue(ControlQueue, ControlQueue)
FrsRtlInitializeQueue(QueueA, ControlQueue)
FrsRtlInitializeQueue(QueueB, ControlQueue)
Queues can be added and deleted from the stripe at any time.
Idling Queues
The controlling queue for a striped queue maintains a list of Full queues,
Empty queues, and Idled queues. A striped queue allows a caller to serialize
access to a queue by "idling" the queue. No other thread is allowed to pull
an entry from the queue until the caller "UnIdles" the queue:
Entry = FrsRtlRemoveHeadTimeoutIdled(Queue, 0, &IdledQueue)
Process Entry
FrsRtlUnIdledQueue(IdledQueue);
Entries can be inserted to an idled queue and they can be removed with
FrsRtlRemoveQueueEntry().
Non-Striped queues do not support the serializing "idling" feature. The
IdledQueue parameter is ignored.
Inserting Entries
Use the normal queue insertion routines for queues, striped queues, and idled
queues. DO NOT insert into the controlling queue if this is a striped queue.
Removing Entries
Use the normal queue removal routines for queues, striped queues, and idled
queues. Removals from a striped queue will return an entry from any of the
sub-queues except for idled sub-queues. The FrsRtlRemoveQueueEntry() function
will remove an entry from even an idled queue.
Functions
DbgCheckLinkage - Checks all of the linkage in a queue
FrsRtlInitializeQueue - Initializes any queue
FrsRtlDeleteQueue - Cleans up any queue
FrsRtlRundownQueue - Aborts the queue and returns a list of entries
FrsRtlUnIdledQueue - Moves a queue from the idle to one of the active lists
FrsRtlRemoveHeadQueue - Remove the head of the queue
FrsRtlRemoveHeadQueueTimeout - Remove the head of the queue
FrsRtlRemoveHeadQueueTimeoutIdled - Remove the head of the queue
FrsRtlRemoveEntryQueueLock - Remove entry from locked queue
FrsRtlInsertTailQueue - Insert entry into queue at tail
FrsRtlInsertTailQueueLock - Insert entry into locked queue at head
FrsRtlInsertHeadQueue - Insert entry into queue at tail
FrsRtlInsertHeadQueueLock - Insert entry into locked queue at head
FrsRtlWaitForQueueFull - wait for an entry to appear on the queue
Rundown
Calling rundown on the controlling queue is NOT supported. Don't do that
Running down a component queue does not rundown the controlling queue.
The abort event is set in the controlling queue when the last component
queue is rundown.
--*/
#include <ntreppch.h>
#pragma hdrstop
#include <frs.h>
VOID
FrsCompleteSynchronousCmdPkt(
IN PCOMMAND_PACKET CmdPkt,
IN PVOID CompletionArg
);
//
// This is the command packet schedule queue. It is used when you need to
// queue a command packet to be processed in the future.
//
FRS_QUEUE FrsScheduleQueue;
// #define PRINT_QUEUE(_S_, _Q_) PrintQueue(_S_, _Q_)
#define PRINT_QUEUE(_S_, _Q_)
VOID
PrintQueue(
IN ULONG Sev,
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Print the queue
Arguments:
Sev - dprint severity
Queue - Supplies a pointer to a queue structure to check
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "PrintQueue:"
DWORD Count;
DWORD ControlCount;
BOOL FoundFull;
BOOL FoundEmpty;
BOOL FoundIdled;
PLIST_ENTRY Entry;
PLIST_ENTRY OtherEntry;
PFRS_QUEUE OtherQueue;
PFRS_QUEUE Control;
DPRINT1(0, "***** Print Queue %08x *****\n", Queue);
Control = Queue->Control;
if (Queue == Control) {
DPRINT1(Sev, "\tQueue : %08x\n", Queue);
DPRINT1(Sev, "\tCount : %8d\n", Queue->Count);
DPRINT1(Sev, "\tControlCount: %8d\n", Queue->ControlCount);
DPRINT1(Sev, "\tRundown : %s\n", (Queue->IsRunDown) ? "TRUE" : "FALSE");
DPRINT1(Sev, "\tIdled : %s\n", (Queue->IsIdled) ? "TRUE" : "FALSE");
return;
}
DPRINT2(Sev, "\tControl : %08x for %08x\n", Control, Queue);
DPRINT1(Sev, "\tCount : %8d\n", Control->Count);
DPRINT1(Sev, "\tControlCount: %8d\n", Control->ControlCount);
DPRINT1(Sev, "\tRundown : %s\n", (Control->IsRunDown) ? "TRUE" : "FALSE");
DPRINT1(Sev, "\tIdled : %s\n", (Control->IsIdled) ? "TRUE" : "FALSE");
//
// Full list
//
DPRINT(Sev, "\tFULL\n");
for (Entry = GetListNext(&Control->Full);
Entry != &Control->Full;
Entry = GetListNext(Entry)) {
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Full);
if (OtherQueue == Queue) {
DPRINT(Sev, "\t\tTHIS QUEUE\n");
}
DPRINT1(Sev, "\t\tQueue : %08x\n", OtherQueue);
DPRINT1(Sev, "\t\tCount : %8d\n", OtherQueue->Count);
DPRINT1(Sev, "\t\tControlCount: %8d\n", OtherQueue->ControlCount);
DPRINT1(Sev, "\t\tRundown : %s\n", (OtherQueue->IsRunDown) ? "TRUE" : "FALSE");
DPRINT1(Sev, "\t\tIdled : %s\n", (OtherQueue->IsIdled) ? "TRUE" : "FALSE");
}
//
// Empty list
//
DPRINT(Sev, "\tEMPTY\n");
for (Entry = GetListNext(&Control->Empty);
Entry != &Control->Empty;
Entry = GetListNext(Entry)) {
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Empty);
if (OtherQueue == Queue) {
DPRINT(Sev, "\t\tTHIS QUEUE\n");
}
DPRINT1(Sev, "\t\tQueue : %08x\n", OtherQueue);
DPRINT1(Sev, "\t\tCount : %8d\n", OtherQueue->Count);
DPRINT1(Sev, "\t\tControlCount: %8d\n", OtherQueue->ControlCount);
DPRINT1(Sev, "\t\tRundown : %s\n", (OtherQueue->IsRunDown) ? "TRUE" : "FALSE");
DPRINT1(Sev, "\t\tIdled : %s\n", (OtherQueue->IsIdled) ? "TRUE" : "FALSE");
}
//
// Idle list
//
DPRINT(Sev, "\tIDLE\n");
for (Entry = GetListNext(&Control->Idled);
Entry != &Control->Idled;
Entry = GetListNext(Entry)) {
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Idled);
if (OtherQueue == Queue) {
DPRINT(Sev, "\t\tTHIS QUEUE\n");
}
DPRINT1(Sev, "\t\tQueue : %08x\n", OtherQueue);
DPRINT1(Sev, "\t\tCount : %8d\n", OtherQueue->Count);
DPRINT1(Sev, "\t\tControlCount: %8d\n", OtherQueue->ControlCount);
DPRINT1(Sev, "\t\tRundown : %s\n", (OtherQueue->IsRunDown) ? "TRUE" : "FALSE");
DPRINT1(Sev, "\t\tIdled : %s\n", (OtherQueue->IsIdled) ? "TRUE" : "FALSE");
}
}
BOOL
DbgCheckQueue(
PFRS_QUEUE Queue
)
/*++
Routine Description:
Check the consistency of the queue
Arguments:
Queue - Supplies a pointer to a queue structure to check
Return Value:
TRUE - everything is okay
Assert - assert error
--*/
{
#undef DEBSUB
#define DEBSUB "DbgCheckQueue:"
DWORD Count;
DWORD ControlCount;
BOOL FoundFull;
BOOL FoundEmpty;
BOOL FoundIdled;
PLIST_ENTRY Entry;
PLIST_ENTRY OtherEntry;
PFRS_QUEUE OtherQueue;
PFRS_QUEUE Control;
if (!DebugInfo.Queues) {
return TRUE;
}
FRS_ASSERT(Queue);
Control = Queue->Control;
FRS_ASSERT(Control);
if (Control->IsRunDown) {
FRS_ASSERT(Control->ControlCount == 0);
FRS_ASSERT(Queue->IsRunDown);
FRS_ASSERT(IsListEmpty(&Control->Full));
FRS_ASSERT(IsListEmpty(&Control->Empty));
FRS_ASSERT(IsListEmpty(&Control->Idled));
}
if (Queue->IsRunDown) {
FRS_ASSERT(Queue->Count == 0);
FRS_ASSERT(IsListEmpty(&Queue->Full));
FRS_ASSERT(IsListEmpty(&Queue->Empty));
FRS_ASSERT(IsListEmpty(&Queue->Idled));
}
FRS_ASSERT(!Control->IsIdled);
//
// Check Full list
//
ControlCount = 0;
FoundFull = FALSE;
Entry = &Control->Full;
do {
Entry = GetListNext(Entry);
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Full);
if (OtherQueue == Queue) {
FoundFull = TRUE;
}
FRS_ASSERT(Control == OtherQueue ||
(!OtherQueue->IsRunDown && !OtherQueue->IsIdled));
Count = 0;
if (!IsListEmpty(&OtherQueue->ListHead)) {
OtherEntry = GetListNext(&OtherQueue->ListHead);
do {
++Count;
++ControlCount;
OtherEntry = GetListNext(OtherEntry);
} while (OtherEntry != &OtherQueue->ListHead);
}
FRS_ASSERT(Count == OtherQueue->Count);
} while (OtherQueue != Control);
FRS_ASSERT(ControlCount == Control->ControlCount ||
(Control == Queue && Control->ControlCount == 0));
//
// Check Empty list
//
ControlCount = 0;
FoundEmpty = FALSE;
Entry = &Control->Empty;
do {
Entry = GetListNext(Entry);
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Empty);
if (OtherQueue == Queue) {
FoundEmpty = TRUE;
}
FRS_ASSERT(Control == OtherQueue ||
(!OtherQueue->IsRunDown && !OtherQueue->IsIdled));
Count = 0;
if (!IsListEmpty(&OtherQueue->ListHead)) {
OtherEntry = GetListNext(&OtherQueue->ListHead);
do {
++Count;
++ControlCount;
OtherEntry = GetListNext(OtherEntry);
} while (OtherEntry != &OtherQueue->ListHead);
}
FRS_ASSERT(Count == OtherQueue->Count);
} while (OtherQueue != Control);
//
// Check Idled list
//
FoundIdled = FALSE;
Entry = &Control->Idled;
do {
Entry = GetListNext(Entry);
OtherQueue = CONTAINING_RECORD(Entry, FRS_QUEUE, Idled);
if (OtherQueue == Queue) {
FoundIdled = TRUE;
}
FRS_ASSERT(Control == OtherQueue || OtherQueue->IsIdled);
Count = 0;
if (!IsListEmpty(&OtherQueue->ListHead)) {
OtherEntry = GetListNext(&OtherQueue->ListHead);
do {
++Count;
OtherEntry = GetListNext(OtherEntry);
} while (OtherEntry != &OtherQueue->ListHead);
}
FRS_ASSERT(Count == OtherQueue->Count);
} while (OtherQueue != Control);
//
// Verify state
//
FRS_ASSERT((Queue->Count && !IsListEmpty(&Queue->ListHead)) ||
(!Queue->Count && IsListEmpty(&Queue->ListHead)));
if (Control == Queue) {
//
// We are our own controlling queue
//
FRS_ASSERT(FoundFull && FoundEmpty && FoundIdled);
} else {
//
// Controlled by a separate queue
//
if (Queue->IsRunDown) {
FRS_ASSERT(!FoundFull && !FoundEmpty && !FoundIdled && !Queue->Count);
} else {
FRS_ASSERT(FoundFull || FoundEmpty || FoundIdled);
}
if (FoundFull) {
FRS_ASSERT(!FoundEmpty && !FoundIdled && Queue->Count);
} else if (FoundEmpty) {
FRS_ASSERT(!FoundFull && !FoundIdled && !Queue->Count);
} else if (FoundIdled) {
FRS_ASSERT(!FoundFull && !FoundEmpty);
}
}
return TRUE;
}
VOID
FrsInitializeQueue(
PFRS_QUEUE Queue,
PFRS_QUEUE Control
)
/*++
Routine Description:
Initializes a queue for use.
Arguments:
Queue - Supplies a pointer to a queue structure to initialize
Return Value:
ERROR_SUCCESS if successful
Win32 error code otherwise.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsInitializeQueue:"
ZeroMemory(Queue, sizeof(FRS_QUEUE));
InitializeListHead(&Queue->ListHead);
InitializeListHead(&Queue->Full);
InitializeListHead(&Queue->Empty);
InitializeListHead(&Queue->Idled);
InitializeCriticalSection(&Queue->Lock);
Queue->IsRunDown = FALSE;
Queue->IsIdled = FALSE;
Queue->Control = Control;
Queue->InitTime = GetTickCount();
if (Control->IsRunDown) {
Queue->IsRunDown = TRUE;
return;
}
//
// Begin life on the empty queue
//
FrsRtlAcquireQueueLock(Queue);
InsertTailList(&Control->Empty, &Queue->Empty);
FRS_ASSERT(DbgCheckQueue(Queue));
FrsRtlReleaseQueueLock(Queue);
//
// The controlling queue supplies the events so there is no
// need to create extraneous events.
//
if (Queue == Control) {
Queue->Event = FrsCreateEvent(TRUE, FALSE);
Queue->RunDown = FrsCreateEvent(TRUE, FALSE);
}
}
VOID
FrsRtlDeleteQueue(
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Releases all resources used by a queue.
Arguments:
Queue - supplies the queue to be deleted
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlDeleteQueue:"
PFRS_QUEUE Control;
Control = Queue->Control;
if (Queue == Control) {
FRS_ASSERT(IsListEmpty(&Queue->Full) &&
IsListEmpty(&Queue->Empty) &&
IsListEmpty(&Queue->Idled));
} else {
FRS_ASSERT(IsListEmpty(&Queue->ListHead));
}
EnterCriticalSection(&Control->Lock);
FRS_ASSERT(DbgCheckQueue(Queue));
RemoveEntryListB(&Queue->Full);
RemoveEntryListB(&Queue->Empty);
RemoveEntryListB(&Queue->Idled);
Control->ControlCount -= Queue->Count;
FRS_ASSERT(DbgCheckQueue(Queue));
LeaveCriticalSection(&Control->Lock);
DeleteCriticalSection(&Queue->Lock);
//
// Only the controlling queue has valid handles
//
if (Queue == Control) {
FRS_CLOSE(Queue->Event);
FRS_CLOSE(Queue->RunDown);
}
//
// Zero the memory in order to cause grief for those who
// use a deleted queue.
//
ZeroMemory(Queue, sizeof(FRS_QUEUE));
}
VOID
FrsRtlRunDownQueue(
IN PFRS_QUEUE Queue,
OUT PLIST_ENTRY ListHead
)
/*++
Routine Description:
Runs down a queue that is about to be destroyed. Any threads currently
waiting on the queue are unwaited (FrsRtlRemoveHeadQueue will return NULL)
and the contents of the queue (if any) are returned to the caller for
cleanup.
Arguments:
Queue - supplies the queue to be rundown
ListHead - returns the list of items currently in the queue.
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlRunDownQueue:"
PFRS_QUEUE Control = Queue->Control;
PLIST_ENTRY Entry;
PLIST_ENTRY First;
PLIST_ENTRY Last;
EnterCriticalSection(&Control->Lock);
//
// Running down a controlling queue is not allowed unless they
// are the same queue.
//
if (Control == Queue) {
FRS_ASSERT(IsListEmpty(&Control->Full) &&
IsListEmpty(&Control->Empty) &&
IsListEmpty(&Control->Idled));
} else {
FRS_ASSERT(!IsListEmpty(&Control->Full) ||
!IsListEmpty(&Control->Empty) ||
!IsListEmpty(&Control->Idled) ||
Control->IsRunDown);
}
/*
FRS_ASSERT((Control == Queue &&
IsListEmpty(&Control->Full) &&
IsListEmpty(&Control->Empty) &&
IsListEmpty(&Control->Idled)
)
||
(Control != Queue &&
(!IsListEmpty(&Control->Full) ||
!IsListEmpty(&Control->Empty) ||
!IsListEmpty(&Control->Idled) ||
Control->IsRunDown
)
)
)
*/
FRS_ASSERT(DbgCheckQueue(Queue));
Queue->IsRunDown = TRUE;
//
// return the list of entries
//
if (IsListEmpty(&Queue->ListHead)) {
InitializeListHead(ListHead);
} else {
*ListHead = Queue->ListHead;
ListHead->Flink->Blink = ListHead;
ListHead->Blink->Flink = ListHead;
}
InitializeListHead(&Queue->ListHead);
//
// Don't update counters if the queue is idled
//
if (!Queue->IsIdled) {
Control->ControlCount -= Queue->Count;
if (Control->ControlCount == 0) {
ResetEvent(Control->Event);
}
}
Queue->Count = 0;
RemoveEntryListB(&Queue->Full);
RemoveEntryListB(&Queue->Empty);
RemoveEntryListB(&Queue->Idled);
FRS_ASSERT(DbgCheckQueue(Queue));
//
// Set the aborted event to awaken any threads currently
// blocked on the queue if the controlling queue has no
// more queues.
//
DPRINT2(4, "Rundown for queue - %08x, Control - %08x\n", Queue, Control);
DPRINT1(4, "Control->Full queue %s empty.\n",
IsListEmpty(&Control->Full) ? "is" : "is not");
DPRINT1(4, "Control->Empty queue %s empty.\n",
IsListEmpty(&Control->Empty) ? "is" : "is not");
DPRINT1(4, "Control->Idled queue %s empty.\n",
IsListEmpty(&Control->Idled) ? "is" : "is not");
if (IsListEmpty(&Control->Full) &&
IsListEmpty(&Control->Empty) &&
IsListEmpty(&Control->Idled)) {
Control->IsRunDown = TRUE;
SetEvent(Control->RunDown);
DPRINT(4, "Setting Control->RunDown event.\n");
}
FRS_ASSERT(DbgCheckQueue(Control));
LeaveCriticalSection(&Control->Lock);
}
VOID
FrsRtlCancelQueue(
IN PFRS_QUEUE Queue,
OUT PLIST_ENTRY ListHead
)
/*++
Routine Description:
Returns the entries on Queue for cancelling.
Arguments:
Queue - supplies the queue to be rundown
ListHead - returns the list of items currently in the queue.
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlCancelQueue:"
PFRS_QUEUE Control = Queue->Control;
PLIST_ENTRY Entry;
PLIST_ENTRY First;
PLIST_ENTRY Last;
EnterCriticalSection(&Control->Lock);
FRS_ASSERT(DbgCheckQueue(Queue));
//
// return the list of entries
//
if (IsListEmpty(&Queue->ListHead)) {
InitializeListHead(ListHead);
} else {
*ListHead = Queue->ListHead;
ListHead->Flink->Blink = ListHead;
ListHead->Blink->Flink = ListHead;
}
InitializeListHead(&Queue->ListHead);
//
// Don't update counters if the queue is idled
//
if (!Queue->IsIdled) {
Control->ControlCount -= Queue->Count;
if (Control->ControlCount == 0) {
ResetEvent(Control->Event);
}
}
Queue->Count = 0;
RemoveEntryListB(&Queue->Full);
RemoveEntryListB(&Queue->Empty);
RemoveEntryListB(&Queue->Idled);
FRS_ASSERT(DbgCheckQueue(Queue));
FRS_ASSERT(DbgCheckQueue(Control));
LeaveCriticalSection(&Control->Lock);
}
VOID
FrsRtlIdleQueue(
IN PFRS_QUEUE Queue
)
{
#undef DEBSUB
#define DEBSUB "FrsRtlIdleQueue:"
/*++
Routine Description:
Idle a queue
Arguments:
Queue - queue to idle
Return Value:
None.
--*/
PFRS_QUEUE Control = Queue->Control;
//
// Queues that don't have a separate controlling queue can't
// support "idling" themselves
//
if (Control == Queue) {
return;
}
//
// Lock the controlling queue
//
EnterCriticalSection(&Control->Lock);
FrsRtlIdleQueueLock(Queue);
LeaveCriticalSection(&Control->Lock);
}
VOID
FrsRtlIdleQueueLock(
IN PFRS_QUEUE Queue
)
{
#undef DEBSUB
#define DEBSUB "FrsRtlIdleQueueLock:"
/*++
Routine Description:
Idle a queue. Caller has the lock already.
Arguments:
Queue - queue to idle
Return Value:
None.
--*/
PFRS_QUEUE Control = Queue->Control;
//
// Queues that don't have a separate controlling queue can't
// support "idling" themselves
//
if (Control == Queue) {
return;
}
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
//
// Stop, this queue has been aborted (rundown)
//
if (Queue->IsRunDown || Queue->IsIdled) {
goto out;
}
if (Queue->Count == 0) {
RemoveEntryListB(&Queue->Empty);
} else {
RemoveEntryListB(&Queue->Full);
}
FRS_ASSERT(IsListEmpty(&Queue->Idled));
InsertTailList(&Control->Idled, &Queue->Idled);
Queue->IsIdled = TRUE;
Control->ControlCount -= Queue->Count;
FRS_ASSERT(DbgCheckQueue(Queue));
if (Control->ControlCount == 0) {
ResetEvent(Control->Event);
}
out:
//
// Done
//
FRS_ASSERT(DbgCheckQueue(Queue));
}
VOID
FrsRtlUnIdledQueue(
IN PFRS_QUEUE IdledQueue
)
{
#undef DEBSUB
#define DEBSUB "FrsRtlUnIdledQueue:"
/*++
Routine Description:
Removes the queue from the "idled" list and puts it back on the
full or empty lists. The controlling queue is updated accordingly.
Arguments:
IdledQueue - Supplies the queue to remove an item from.
Return Value:
None.
--*/
DWORD OldControlCount;
PFRS_QUEUE Control = IdledQueue->Control;
//
// Queues that don't have a separate controlling queue can't
// support "idling" themselves
//
if (Control == IdledQueue) {
return;
}
//
// Lock the controlling queue
//
EnterCriticalSection(&Control->Lock);
FrsRtlUnIdledQueueLock(IdledQueue);
LeaveCriticalSection(&Control->Lock);
}
VOID
FrsRtlUnIdledQueueLock(
IN PFRS_QUEUE IdledQueue
)
{
#undef DEBSUB
#define DEBSUB "FrsRtlUnIdledQueueLock:"
/*++
Routine Description:
Removes the queue from the "idled" list and puts it back on the
full or empty lists. The controlling queue is updated accordingly.
Caller has lock on controlling queue.
Arguments:
IdledQueue - Supplies the queue to remove an item from.
Return Value:
None.
--*/
DWORD OldControlCount;
PFRS_QUEUE Control = IdledQueue->Control;
//
// Queues that don't have a separate controlling queue can't
// support "idling" themselves
//
if (Control == IdledQueue) {
return;
}
PRINT_QUEUE(5, IdledQueue);
FRS_ASSERT(DbgCheckQueue(IdledQueue));
//
// Stop, this queue has been aborted (rundown)
//
if (IdledQueue->IsRunDown) {
goto out;
}
//
// Remove from idled list
//
FRS_ASSERT(IdledQueue->IsIdled);
RemoveEntryListB(&IdledQueue->Idled);
IdledQueue->IsIdled = FALSE;
//
// Put onto full or empty list
//
if (IdledQueue->Count) {
InsertTailList(&Control->Full, &IdledQueue->Full);
} else {
InsertTailList(&Control->Empty, &IdledQueue->Empty);
}
//
// Wakeup sleepers if count is now > 0
//
OldControlCount = Control->ControlCount;
Control->ControlCount += IdledQueue->Count;
if (Control->ControlCount && OldControlCount == 0) {
SetEvent(Control->Event);
}
//
// Done
//
out:
FRS_ASSERT(DbgCheckQueue(IdledQueue));
}
PLIST_ENTRY
FrsRtlRemoveHeadQueueTimeoutIdled(
IN PFRS_QUEUE Queue,
IN DWORD dwMilliseconds,
OUT PFRS_QUEUE *IdledQueue
)
/*++
Routine Description:
Removes the item at the head of the queue. If the queue is empty,
blocks until an item is inserted into the queue.
Arguments:
Queue - Supplies the queue to remove an item from.
Timeout - Supplies a timeout value that specifies the relative
time, in milliseconds, over which the wait is to be completed.
IdledQueue - If non-NULL then on return this will be the address
of the queue from which the entry was retrieved. Or NULL if
the returned entry is NULL. No other thread will be allowed
to pull an entry from the returned queue until that queue is
released with FrsRtlUnIdledQueue(*IdledQueue).
Return Value:
Pointer to list entry removed from the head of the queue.
NULL if the wait times out or the queue is run down. If this
routine returns NULL, GetLastError will return either
ERROR_INVALID_HANDLE (if the queue has been rundown) or
WAIT_TIMEOUT (to indicate a timeout has occurred)
IdledQueue - If non-NULL then on return this will be the address
of the queue from which the entry was retrieved. Or NULL if
the returned entry is NULL. No other thread will be allowed
to pull an entry from the returned queue until that queue is
released with FrsRtlUnIdledQueue(*IdledQueue).
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlRemoveHeadQueueTimeoutIdled:"
DWORD Status;
PLIST_ENTRY Entry;
HANDLE WaitArray[2];
PFRS_QUEUE Control = Queue->Control;
//
// No idled queue at this time
//
if (IdledQueue) {
*IdledQueue = NULL;
}
Retry:
if (Control->ControlCount == 0) {
//
// Block until something is inserted on the queue
//
WaitArray[0] = Control->RunDown;
WaitArray[1] = Control->Event;
Status = WaitForMultipleObjects(2, WaitArray, FALSE, dwMilliseconds);
if (Status == 0) {
//
// The queue has been rundown, return NULL immediately.
//
SetLastError(ERROR_INVALID_HANDLE);
return(NULL);
} else if (Status == WAIT_TIMEOUT) {
SetLastError(WAIT_TIMEOUT);
return(NULL);
}
FRS_ASSERT(Status == 1);
}
//
// Lock the queue and try to remove something
//
EnterCriticalSection(&Control->Lock);
PRINT_QUEUE(5, Queue);
if (Control->ControlCount == 0) {
//
// Somebody got here before we did, drop the lock and retry
//
LeaveCriticalSection(&Control->Lock);
goto Retry;
}
FRS_ASSERT(DbgCheckQueue(Queue));
Entry = GetListNext(&Control->Full);
RemoveEntryListB(Entry);
Queue = CONTAINING_RECORD(Entry, FRS_QUEUE, Full);
Entry = RemoveHeadList(&Queue->ListHead);
//
// update counters
//
--Queue->Count;
--Control->ControlCount;
//
// A separate controlling queue is required for idling
//
if (IdledQueue && Queue != Control) {
//
// Idle the queue
//
FRS_ASSERT(IsListEmpty(&Queue->Idled));
FRS_ASSERT(!Queue->IsIdled);
InsertTailList(&Control->Idled, &Queue->Idled);
Queue->IsIdled = TRUE;
Control->ControlCount -= Queue->Count;
*IdledQueue = Queue;
} else if (Queue->Count) {
//
// Queue still has entries
//
InsertTailList(&Control->Full, &Queue->Full);
} else {
//
// Queue is empty
//
InsertTailList(&Control->Empty, &Queue->Empty);
}
//
// Queues are empty (or idled)
//
if (Control->ControlCount == 0) {
ResetEvent(Control->Event);
}
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
LeaveCriticalSection(&Control->Lock);
return(Entry);
}
PLIST_ENTRY
FrsRtlRemoveHeadQueue(
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Removes the item at the head of the queue. If the queue is empty,
blocks until an item is inserted into the queue.
Arguments:
Queue - Supplies the queue to remove an item from.
Return Value:
Pointer to list entry removed from the head of the queue.
--*/
{
return(FrsRtlRemoveHeadQueueTimeoutIdled(Queue, INFINITE, NULL));
}
PLIST_ENTRY
FrsRtlRemoveHeadQueueTimeout(
IN PFRS_QUEUE Queue,
IN DWORD dwMilliseconds
)
/*++
Routine Description:
Removes the item at the head of the queue. If the queue is empty,
blocks until an item is inserted into the queue.
Arguments:
Queue - Supplies the queue to remove an item from.
Timeout - Supplies a timeout value that specifies the relative
time, in milliseconds, over which the wait is to be completed.
Return Value:
Pointer to list entry removed from the head of the queue.
NULL if the wait times out or the queue is run down. If this
routine returns NULL, GetLastError will return either
ERROR_INVALID_HANDLE (if the queue has been rundown) or
WAIT_TIMEOUT (to indicate a timeout has occurred)
--*/
{
return(FrsRtlRemoveHeadQueueTimeoutIdled(Queue, dwMilliseconds, NULL));
}
VOID
FrsRtlRemoveEntryQueue(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Removes the entry from the queue. The entry is assumed to be on the
queue since we derement the queue count.
Arguments:
Queue - Supplies the queue to remove an item from.
Entry - pointer to the entry to remove.
Return Value:
none.
--*/
{
FrsRtlAcquireQueueLock(Queue);
FrsRtlRemoveEntryQueueLock(Queue, Entry);
FrsRtlReleaseQueueLock(Queue);
}
VOID
FrsRtlRemoveEntryQueueLock(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Removes the entry from the queue. The entry is assumed to be on the
queue since we derement the queue count. We also assume the caller
has acquired the queue lock since this was needed to scan the queue
in the first place to find the entry in question.
The LOCK suffix means the caller has already acquired the lock.
Arguments:
Queue - Supplies the queue to remove an item from.
Entry - pointer to the entry to remove.
Return Value:
none.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlRemoveEntryQueueLock:"
PFRS_QUEUE Control = Queue->Control;
FRS_ASSERT(Queue->Count != 0);
FRS_ASSERT(!IsListEmpty(&Queue->ListHead));
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
RemoveEntryListB(Entry);
//
// If the queue is idled then just update the count
//
--Queue->Count;
if (!Queue->IsIdled) {
//
// Queue is empty; remove from full list
//
if (Queue->Count == 0) {
RemoveEntryListB(&Queue->Full);
InsertTailList(&Control->Empty, &Queue->Empty);
}
//
// Control queue is empty
//
if (--Control->ControlCount == 0) {
ResetEvent(Control->Event);
}
}
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
return;
}
DWORD
FrsRtlInsertTailQueue(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Item
)
/*++
Routine Description:
Inserts a new entry on the tail of the queue.
Arguments:
Queue - Supplies the queue to add the entry to.
Item - Supplies the entry to be added to the queue.
Return Value:
ERROR_SUCCESS and the item is queueed. Otherwise, the item
is not queued.
--*/
{
DWORD Status;
FrsRtlAcquireQueueLock(Queue);
Status = FrsRtlInsertTailQueueLock(Queue, Item);
FrsRtlReleaseQueueLock(Queue);
return Status;
}
DWORD
FrsRtlInsertTailQueueLock(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Item
)
/*++
Routine Description:
Inserts a new entry on the tail of the queue. Caller already has the
queue lock.
Arguments:
Queue - Supplies the queue to add the entry to.
Item - Supplies the entry to be added to the queue.
Return Value:
ERROR_SUCCESS and the item is queueed. Otherwise, the item
is not queued.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlInsertTailQueueLock:"
PFRS_QUEUE Control = Queue->Control;
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
if (Queue->IsRunDown) {
return ERROR_ACCESS_DENIED;
}
InsertTailList(&Queue->ListHead, Item);
//
// If the queue is idled then just update the count
//
if (Queue->IsIdled) {
++Queue->Count;
} else {
//
// Queue is transitioning from empty to full
//
if (++Queue->Count == 1) {
RemoveEntryListB(&Queue->Empty);
InsertTailList(&Control->Full, &Queue->Full);
}
//
// Controlling queue is transitioning from empty to full
//
if (++Control->ControlCount == 1) {
SetEvent(Control->Event);
}
}
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
return ERROR_SUCCESS;
}
DWORD
FrsRtlInsertHeadQueue(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Item
)
/*++
Routine Description:
Inserts a new entry on the tail of the queue.
Arguments:
Queue - Supplies the queue to add the entry to.
Item - Supplies the entry to be added to the queue.
Return Value:
ERROR_SUCCESS and the item is queueed. Otherwise, the item
is not queued.
--*/
{
DWORD Status;
FrsRtlAcquireQueueLock(Queue);
Status = FrsRtlInsertHeadQueueLock(Queue, Item);
FrsRtlReleaseQueueLock(Queue);
return Status;
}
DWORD
FrsRtlInsertHeadQueueLock(
IN PFRS_QUEUE Queue,
IN PLIST_ENTRY Item
)
/*++
Routine Description:
Inserts a new entry on the head of the queue.
Caller already has the queue lock.
Arguments:
Queue - Supplies the queue to add the entry to.
Item - Supplies the entry to be added to the queue.
Return Value:
ERROR_SUCCESS and the item is queueed. Otherwise, the item
is not queued.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlInsertHeadQueueLock:"
PFRS_QUEUE Control = Queue->Control;
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
if (Queue->IsRunDown) {
return ERROR_ACCESS_DENIED;
}
InsertHeadList(&Queue->ListHead, Item);
//
// If the queue is idled then just update the count
//
if (Queue->IsIdled) {
++Queue->Count;
} else {
//
// Queue is transitioning from empty to full
//
if (++Queue->Count == 1) {
RemoveEntryListB(&Queue->Empty);
InsertTailList(&Control->Full, &Queue->Full);
}
//
// Controlling queue is transitioning from empty to full
//
if (++Control->ControlCount == 1) {
SetEvent(Control->Event);
}
}
PRINT_QUEUE(5, Queue);
FRS_ASSERT(DbgCheckQueue(Queue));
return ERROR_SUCCESS;
}
DWORD
FrsRtlWaitForQueueFull(
IN PFRS_QUEUE Queue,
IN DWORD dwMilliseconds
)
/*++
Routine Description:
Waits until the queue is non-empty. Returns immediately if queue is
non-empty else wait on insert or timeout.
Arguments:
Queue - Supplies the queue to wait on.
Timeout - Supplies a timeout value that specifies the relative
time, in milliseconds, over which the wait is to be completed.
Return Value:
Win32 Status:
ERROR_SUCCESS if queue is now non-empty.
ERROR_INVALID_HANDLE if the queue has been rundown.
WAIT_TIMEOUT to indicate a timeout has occurred.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlWaitForQueueFull:"
DWORD Status;
HANDLE WaitArray[2];
PFRS_QUEUE Control = Queue->Control;
Retry:
if (Control->ControlCount == 0) {
//
// Block until something is inserted on the queue
//
WaitArray[0] = Control->RunDown;
WaitArray[1] = Control->Event;
Status = WaitForMultipleObjects(2, WaitArray, FALSE, dwMilliseconds);
if (Status == 0) {
//
// The queue has been rundown, return immediately.
//
return(ERROR_INVALID_HANDLE);
}
if (Status == WAIT_TIMEOUT) {
return(WAIT_TIMEOUT);
}
FRS_ASSERT(Status == 1);
}
//
// Lock the queue and check again.
//
EnterCriticalSection(&Control->Lock);
if (Control->ControlCount == 0) {
//
// Somebody got here before we did, drop the lock and retry
//
LeaveCriticalSection(&Control->Lock);
goto Retry;
}
LeaveCriticalSection(&Control->Lock);
return(ERROR_SUCCESS);
}
VOID
FrsSubmitCommand(
IN PCOMMAND_PACKET CmdPkt,
IN BOOL Headwise
)
/*++
Routine Description:
Insert the command packet on the command's target queue.
If the time delay parameter is non-zero the command is instead
queued to the scheduler thread to initiate at the specified time.
FrsCompleteCommand(Status) is called if the packet could not be
queued.
Arguments:
CmdPkt
Headwise - Queue at the head (high priority)
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsSubmitCommand:"
DWORD WStatus;
//
// Queue to the target
//
if (Headwise) {
WStatus = FrsRtlInsertHeadQueue(CmdPkt->TargetQueue, &CmdPkt->ListEntry);
} else {
WStatus = FrsRtlInsertTailQueue(CmdPkt->TargetQueue, &CmdPkt->ListEntry);
}
if (!WIN_SUCCESS(WStatus)) {
FrsCompleteCommand(CmdPkt, WStatus);
}
}
ULONG
FrsSubmitCommandAndWait(
IN PCOMMAND_PACKET Cmd,
IN BOOL Headwise,
IN ULONG Timeout
)
/*++
Routine Description:
Create or Reset the event, Submit the command and wait for the return.
Arguments:
Cmd - command packet to queue
Timeout - Wait Timeout
Headwise - if True, insert to head.
Return Value:
Win32 status
--*/
{
#undef DEBSUB
#define DEBSUB "FrsSubmitCommandAndWait:"
DWORD WStatus;
//
// Set the synchronous flag in the command packet.
//
FrsSetCommandSynchronous(Cmd);
if (!HANDLE_IS_VALID(Cmd->WaitEvent)){
Cmd->WaitEvent = FrsCreateEvent(TRUE, FALSE);
} else {
ResetEvent(Cmd->WaitEvent);
}
//
// Save the callers completion routine and replace it with a function
// that signals the event. It does not delete the packet so we can
// return the command status to the caller.
//
Cmd->SavedCompletionRoutine = Cmd->CompletionRoutine;
Cmd->CompletionRoutine = FrsCompleteSynchronousCmdPkt;
//
// Queue the command and create a thread if needed.
//
FrsSubmitCommand(Cmd, Headwise);
//
// Wait for the command to complete.
//
WStatus = WaitForSingleObject(Cmd->WaitEvent, Timeout);
CHECK_WAIT_ERRORS(3, WStatus, 1, ACTION_RETURN);
//
// Return the command error status.
//
WStatus = Cmd->ErrorStatus;
//
// Restore and call the caller's completion routine. This may free the
// the packet. We don't call FrsCompleteCommand() here because it was
// already called when the server finished the packet and there is no
// point in setting the wait event twice.
//
Cmd->CompletionRoutine = Cmd->SavedCompletionRoutine;
FRS_ASSERT(Cmd->CompletionRoutine != NULL);
(Cmd->CompletionRoutine)(Cmd, Cmd->CompletionArg);
return WStatus;
}
#define HEADWISE TRUE
VOID
FrsUnSubmitCommand(
IN PCOMMAND_PACKET Cmd
)
/*++
Routine Description:
Put the entry back on the head of the queue.
Arguments:
Cmd
Return Value:
None.
--*/
{
FrsSubmitCommand(Cmd, HEADWISE);
}
VOID
FrsCompleteCommand(
IN PCOMMAND_PACKET CmdPkt,
IN DWORD ErrorStatus
)
/*++
Routine Description:
Retire the command packet based on what the original requestor specified
in the packet. The ErrorStatus is returned in the packet.
The completion routine is called for clean up and propagation.
Arguments:
CmdPkt -- A ptr to the command packet.
ErrorStatus -- Status to store in returned command packet.
Return Value:
None.
--*/
{
//
// Set the error status and call the completion routine
//
CmdPkt->ErrorStatus = ErrorStatus;
FRS_ASSERT(CmdPkt->CompletionRoutine != NULL);
(CmdPkt->CompletionRoutine)(CmdPkt, CmdPkt->CompletionArg);
}
VOID
FrsInitializeCommandServer(
IN PCOMMAND_SERVER Cs,
IN DWORD MaxThreads,
IN PWCHAR Name,
IN DWORD (*Main)(PVOID)
)
/*++
Routine Description:
Initialize a command server
Arguments:
Cs - command server
MaxThreads - Max # of threads to kick off
Name - Printable name for thread
Main - Thread starts here
Return Value:
None.
--*/
{
ZeroMemory(Cs, sizeof(COMMAND_SERVER));
FrsInitializeQueue(&Cs->Control, &Cs->Control);
FrsInitializeQueue(&Cs->Queue, &Cs->Control);
Cs->Main = Main;
Cs->Name = Name;
Cs->MaxThreads = MaxThreads;
Cs->Idle = FrsCreateEvent(TRUE, TRUE);
}
VOID
FrsDeleteCommandServer(
IN PCOMMAND_SERVER Cs
)
/*++
Routine Description:
Undo the work of FrsInitializeCommandServer(). This function
assumes the queue and its control queue are inactive (whatever
that means). Queues and command servers are normally only
deleted at the very end of MainFrsShutDown() when all other threads
have exited and the RPC servers aren't listening for new requests.
The caller is responsible for handling all of the other queues
that may be being controlled by the control queue in the command
server struct, Cs.
Arguments:
Cs - command server
Return Value:
None.
--*/
{
if (Cs) {
FrsRtlDeleteQueue(&Cs->Queue);
FrsRtlDeleteQueue(&Cs->Control);
ZeroMemory(Cs, sizeof(COMMAND_SERVER));
}
}
PCOMMAND_PACKET
FrsAllocCommand(
IN PFRS_QUEUE TargetQueue,
IN USHORT Command
)
/*++
Routine Description:
Allocate a command packet and initialize the most common fields.
Arguments:
TargetQueue
Command
Return Value:
Address of allocated, initialized COMMAND_PACKET. Call
FrsCompleteCommand() when done.
--*/
{
PCOMMAND_PACKET Cmd;
Cmd = FrsAllocType(COMMAND_PACKET_TYPE);
Cmd->TargetQueue = TargetQueue;
FrsSetCompletionRoutine(Cmd, FrsFreeCommand, NULL);
Cmd->Command = Command;
return Cmd;
}
PCOMMAND_PACKET
FrsAllocCommandEx(
IN PFRS_QUEUE TargetQueue,
IN USHORT Command,
IN ULONG Size
)
/*++
Routine Description:
Allocate a command packet with some extra space
and initialize the most common fields.
Arguments:
TargetQueue
Command
Return Value:
Address of allocated, initialized COMMAND_PACKET. Call
FrsCompleteCommand() when done.
--*/
{
PCOMMAND_PACKET Cmd;
Cmd = FrsAllocTypeSize(COMMAND_PACKET_TYPE, Size);
Cmd->TargetQueue = TargetQueue;
Cmd->CompletionRoutine = FrsFreeCommand;
Cmd->Command = Command;
return Cmd;
}
VOID
FrsFreeCommand(
IN PCOMMAND_PACKET Cmd,
IN PVOID CompletionArg
)
/*++
Routine Description:
Free a command packet
Arguments:
Cmd - command packet allocated with FrsAllocCommand().
Return Value:
NULL
--*/
{
ULONG WStatus;
if (((Cmd->Flags & CMD_PKT_FLAGS_SYNC) != 0) &&
(HANDLE_IS_VALID(Cmd->WaitEvent))){
//
// Close the event handle. The command complete function should have
// already set the event.
//
if (!CloseHandle(Cmd->WaitEvent)) {
WStatus = GetLastError();
DPRINT_WS(0, "ERROR: Close event handle failed", WStatus);
// Don't free the packet if the close handle failed.
return;
}
Cmd->WaitEvent = NULL;
}
FrsFreeType(Cmd);
}
VOID
FrsExitCommandServer(
IN PCOMMAND_SERVER Cs,
IN PFRS_THREAD FrsThread
)
/*++
Routine Description:
Exit the calling command server thread.
Arguments:
Cs - command server
Thread - calling thread
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsExitCommandServer:"
PFRS_QUEUE Queue = &Cs->Queue;
//
// If there is work to be done
//
FrsRtlAcquireQueueLock(Queue);
--Cs->FrsThreads;
if (FrsRtlCountQueue(Queue) && Cs->Waiters == 0 && Cs->FrsThreads == 0) {
//
// and no one to do it; don't exit
//
++Cs->FrsThreads;
FrsRtlReleaseQueueLock(Queue);
return;
}
//
// Set the idle event if all threads are waiting, there are no entries
// on the queue, and there are no idled queues
//
if (Cs->Waiters == Cs->FrsThreads) {
if (FrsRtlCountQueue(&Cs->Queue) == 0) {
if (FrsRtlNoIdledQueues(&Cs->Queue)) {
SetEvent(Cs->Idle);
}
}
}
FrsRtlReleaseQueueLock(Queue);
//
// The thread command server (ThQs) will "wait" on this thread's exit
// and drop the reference on its thread struct.
//
ThSupSubmitThreadExitCleanup(FrsThread);
//
// Exit
//
ExitThread(ERROR_SUCCESS);
}
#define TAILWISE FALSE
VOID
FrsSubmitCommandServer(
IN PCOMMAND_SERVER Cs,
IN PCOMMAND_PACKET Cmd
)
/*++
Routine Description:
If needed, create a thread for the command queue
Arguments:
Cs - command server
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsSubmitCommandServer:"
//
// Enqueue the command and make sure there are threads running
//
FRS_ASSERT(Cmd && Cmd->TargetQueue && Cs &&
Cmd->TargetQueue->Control == &Cs->Control);
FrsSubmitCommand(Cmd, TAILWISE);
FrsKickCommandServer(Cs);
}
ULONG
FrsSubmitCommandServerAndWait(
IN PCOMMAND_SERVER Cs,
IN PCOMMAND_PACKET Cmd,
IN ULONG Timeout
)
/*++
Routine Description:
Create or Reset the event, Submit the command and wait for the return.
If needed, create a thread for the command queue.
Arguments:
Cs - command server
Cmd - command packet to queue
Timeout - Wait Timeout
Return Value:
Win32 status
--*/
{
#undef DEBSUB
#define DEBSUB "FrsSubmitCommandServerAndWait:"
DWORD WStatus;
//
// Enqueue the command and make sure there are threads running
//
FRS_ASSERT(Cmd && Cmd->TargetQueue && Cs &&
Cmd->TargetQueue->Control == &Cs->Control);
//
// Set the synchronous flag in the command packet.
//
FrsSetCommandSynchronous(Cmd);
if (!HANDLE_IS_VALID(Cmd->WaitEvent)){
Cmd->WaitEvent = FrsCreateEvent(TRUE, FALSE);
} else {
ResetEvent(Cmd->WaitEvent);
}
//
// Save the callers completion routine and replace it with a function
// that signals the event. It does not delete the packet so we can
// return the command status to the caller.
//
Cmd->SavedCompletionRoutine = Cmd->CompletionRoutine;
Cmd->CompletionRoutine = FrsCompleteSynchronousCmdPkt;
//
// Queue the command and create a thread if needed.
//
FrsSubmitCommand(Cmd, TAILWISE);
FrsKickCommandServer(Cs);
//
// Wait for the command to complete.
//
WStatus = WaitForSingleObject(Cmd->WaitEvent, Timeout);
CHECK_WAIT_ERRORS(3, WStatus, 1, ACTION_RETURN);
//
// Return the command error status.
//
WStatus = Cmd->ErrorStatus;
//
// Restore and call the caller's completion routine. This may free the
// the packet. We don't call FrsCompleteCommand() here because it was
// already called when the server finished the packet and there is no
// point in setting the wait event twice.
//
Cmd->CompletionRoutine = Cmd->SavedCompletionRoutine;
FRS_ASSERT(Cmd->CompletionRoutine != NULL);
(Cmd->CompletionRoutine)(Cmd, Cmd->CompletionArg);
return WStatus;
}
#define THREAD_CREATE_RETRY (10 * 1000) // 10 seconds
VOID
FrsKickCommandServer(
IN PCOMMAND_SERVER Cs
)
/*++
Routine Description:
If needed, create a thread for the command queue
Arguments:
Cs - command server
Return Value:
None.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsKickCommandServer:"
PFRS_QUEUE Queue = &Cs->Queue;
//
// Kick off more threads if no one is waiting for this command
// and the number of threads serving this command queue is less
// than the maximum.
//
// If the thread cannot be created and there are no threads
// processing the command queue then put this command on the
// delayed queue and try again later
//
FrsRtlAcquireQueueLock(Queue);
//
// There are entries on the queue
//
if (FrsRtlCountQueue(Queue)) {
//
// But there are no threads to process the entries
//
if (Cs->Waiters == 0 && Cs->FrsThreads < Cs->MaxThreads) {
//
// First thread; reset idle
//
if (Cs->FrsThreads == 0) {
ResetEvent(Cs->Idle);
}
if (ThSupCreateThread(Cs->Name, Cs, Cs->Main, ThSupExitThreadNOP)) {
//
// Created a new thread
//
++Cs->FrsThreads;
} else if (Cs->FrsThreads == 0) {
//
// Thread could not be created and there are no other
// threads to process this entry. Put it on the delayed
// queue and try again in a few seconds.
//
FrsDelCsSubmitKick(Cs, &Cs->Queue, THREAD_CREATE_RETRY);
}
}
}
FrsRtlReleaseQueueLock(Queue);
}
PCOMMAND_PACKET
FrsGetCommandIdled(
IN PFRS_QUEUE Queue,
IN DWORD MilliSeconds,
IN PFRS_QUEUE *IdledQueue
)
/*++
Routine Description:
Get the next command from the queue; idling the queue if requested.
Arguments:
Queue
MilliSeconds
IdledQueue
Return Value:
COMMAND_PACKET or NULL.
If non-NULL, IdledQueue is set
--*/
{
PLIST_ENTRY Entry;
Entry = FrsRtlRemoveHeadQueueTimeoutIdled(Queue, MilliSeconds, IdledQueue);
if (Entry == NULL) {
return NULL;
}
//
// Return the command packet
//
return CONTAINING_RECORD(Entry, COMMAND_PACKET, ListEntry);
}
PCOMMAND_PACKET
FrsGetCommand(
IN PFRS_QUEUE Queue,
IN DWORD MilliSeconds
)
/*++
Routine Description:
Get the next command from the queue.
Arguments:
Queue
MilliSeconds
Return Value:
COMMAND_PACKET or NULL.
--*/
{
return FrsGetCommandIdled(Queue, MilliSeconds, NULL);
}
PCOMMAND_PACKET
FrsGetCommandServerTimeoutIdled(
IN PCOMMAND_SERVER Cs,
IN ULONG Timeout,
OUT PFRS_QUEUE *IdledQueue,
OUT PBOOL IsRunDown
)
/*++
Routine Description:
Get the next command from the queue for the command server.
If nothing appears on the queue in the specified time, then
return NULL and set IsRunDown.
Arguments:
Cs - command server
Timeout
IdledQueue - Idled queue
IsRunDown
Return Value:
COMMAND_PACKET or NULL. If NULL, IsRunDown indicates whether
the NULL was caused by a rundown queue or a simple timeout.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsGetCommandServerTimeoutIdled:"
PCOMMAND_PACKET Cmd;
//
// Pull off the next entry (wait at most 5 minutes)
//
FrsRtlAcquireQueueLock(&Cs->Queue);
++Cs->Waiters;
//
// Set the idle event if all threads are waiting, there are no entries
// on the queue, and there are no idled queues
//
if (Cs->Waiters == Cs->FrsThreads) {
if (FrsRtlCountQueue(&Cs->Queue) == 0) {
if (FrsRtlNoIdledQueues(&Cs->Queue)) {
SetEvent(Cs->Idle);
}
}
}
FrsRtlReleaseQueueLock(&Cs->Queue);
//
// Get the next command
//
Cmd = FrsGetCommandIdled(&Cs->Control, Timeout, IdledQueue);
FrsRtlAcquireQueueLock(&Cs->Queue);
//
// Reset the Idle event if there is any chance it might have been set
//
if (Cs->Waiters == Cs->FrsThreads) {
ResetEvent(Cs->Idle);
}
--Cs->Waiters;
if (IsRunDown) {
*IsRunDown = Cs->Queue.IsRunDown;
}
FrsRtlReleaseQueueLock(&Cs->Queue);
return Cmd;
}
#define COMMAND_SERVER_TIMEOUT (5 * 60 * 1000) // 5 minutes
DWORD FrsCommandServerTimeout = COMMAND_SERVER_TIMEOUT;
PCOMMAND_PACKET
FrsGetCommandServerIdled(
IN PCOMMAND_SERVER Cs,
IN PFRS_QUEUE *IdledQueue
)
/*++
Routine Description:
Get the next command from the queue. If nothing appears on the queue
for 5 minutes, return NULL. The caller will exit. Idle the queue.
Arguments:
Cs - command server
IdledQueue - Idled queue
Return Value:
COMMAND_PACKET or NULL. Caller should exit on NULL.
If non-NULL, IdledQueue is set
--*/
{
return FrsGetCommandServerTimeoutIdled(Cs,
FrsCommandServerTimeout,
IdledQueue,
NULL);
}
PCOMMAND_PACKET
FrsGetCommandServerTimeout(
IN PCOMMAND_SERVER Cs,
IN ULONG Timeout,
OUT PBOOL IsRunDown
)
/*++
Routine Description:
Get the next command from the queue. If nothing appears on the queue
in the specified timeout, return NULL and an indication of the
queue's rundown status.
Arguments:
Cs - command server
Timeout
IsRunDown
Return Value:
COMMAND_PACKET or NULL. IsRunDown is only valid if COMMAND_PACKET
is NULL. Use IsRunDown to check if the NULL return is because of
a rundown'ed queue or simply a timeout.
--*/
{
return FrsGetCommandServerTimeoutIdled(Cs, Timeout, NULL, IsRunDown);
}
DWORD
FrsWaitForCommandServer(
IN PCOMMAND_SERVER Cs,
IN DWORD MilliSeconds
)
/*++
Routine Description:
Wait until all of the threads are idle, there are no entries on the
queue, and there are no idled queues.
Arguments:
Cs - command server
MilliSeconds - Timeout
Return Value:
Status from WaitForSingleObject()
--*/
{
return WaitForSingleObject(Cs->Idle, MilliSeconds);
}
PCOMMAND_PACKET
FrsGetCommandServer(
IN PCOMMAND_SERVER Cs
)
/*++
Routine Description:
Get the next command from the queue. If nothing appears on the queue
for 5 minutes, return NULL. The caller will exit.
Arguments:
Cs - command server
Return Value:
COMMAND_PACKET or NULL. Caller should exit on NULL.
--*/
{
//
// Pull off the next entry (wait at most 5 minutes)
//
return FrsGetCommandServerIdled(Cs, NULL);
}
VOID
FrsRunDownCommand(
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Rundown a queue of command packets
Arguments:
Queue - queue to rundown
Return Value:
None.
--*/
{
LIST_ENTRY RunDown;
PLIST_ENTRY Entry;
PCOMMAND_PACKET Cmd;
if (!Queue) {
return;
}
//
// RunDown the queue and retrieve the current entries
//
FrsRtlRunDownQueue(Queue, &RunDown);
//
// Free up the commands
//
while (!IsListEmpty(&RunDown)) {
Entry = RemoveHeadList(&RunDown);
Cmd = CONTAINING_RECORD(Entry, COMMAND_PACKET, ListEntry);
FrsCompleteCommand(Cmd, ERROR_ACCESS_DENIED);
}
}
VOID
FrsRunDownCommandServer(
IN PCOMMAND_SERVER Cs,
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Rundown a queue of a command server
Arguments:
Cs - command server
Queue - queue to abort
Return Value:
None.
--*/
{
FrsRunDownCommand(Queue);
}
VOID
FrsCancelCommandServer(
IN PCOMMAND_SERVER Cs,
IN PFRS_QUEUE Queue
)
/*++
Routine Description:
Cancels the current commands on Queue.
Arguments:
Cs - command server
Queue - queue to abort
Return Value:
None.
--*/
{
LIST_ENTRY Cancel;
PLIST_ENTRY Entry;
PCOMMAND_PACKET Cmd;
//
// RunDown the queue and retrieve the current entries
//
FrsRtlCancelQueue(Queue, &Cancel);
//
// Free up the commands
//
while (!IsListEmpty(&Cancel)) {
Entry = RemoveHeadList(&Cancel);
Cmd = CONTAINING_RECORD(Entry, COMMAND_PACKET, ListEntry);
FrsCompleteCommand(Cmd, ERROR_CANCELLED);
}
}
VOID
FrsCompleteRequestCount(
IN PCOMMAND_PACKET CmdPkt,
IN PFRS_REQUEST_COUNT RequestCount
)
/*++
Routine Description:
This is an Frs Command packet completion routine that takes
an FRS_REQUEST_COUNT struct. It decrements the count and signals
the event when the count goes to zero. The ErrorStatus is
merged into the Status field of the request count struct.
It then frees the command packet.
Arguments:
CmdPkt -- A ptr to the command packet.
RequestCount - Supplies a pointer to a RequestCount structure to initialize
Return Value:
None.
--*/
{
//
// Decrement count and signal waiter. merge error status from packet
// into RequestCount->Status.
//
FrsDecrementRequestCount(RequestCount, CmdPkt->ErrorStatus);
FrsSetCompletionRoutine(CmdPkt, FrsFreeCommand, NULL);
FrsCompleteCommand(CmdPkt, CmdPkt->ErrorStatus);
}
VOID
FrsCompleteRequestCountKeepPkt(
IN PCOMMAND_PACKET CmdPkt,
IN PFRS_REQUEST_COUNT RequestCount
)
/*++
Routine Description:
This is an Frs Command packet completion routine that takes
an FRS_REQUEST_COUNT struct. It decrements the count and signals
the event when the count goes to zero. The ErrorStatus is
merged into the Status field of the request count struct.
It does not free the command packet so the caller can retreive results
or reuse it.
Arguments:
CmdPkt -- A ptr to the command packet.
RequestCount - Supplies a pointer to a RequestCount structure to initialize
Return Value:
None.
--*/
{
// Decrement count and signal waiter. merge error status from packet
// into RequestCount->Status.
//
FrsDecrementRequestCount(RequestCount, CmdPkt->ErrorStatus);
}
VOID
FrsCompleteKeepPkt(
IN PCOMMAND_PACKET CmdPkt,
IN PVOID CompletionArg
)
/*++
Routine Description:
This is an Frs Command packet completion routine that
leaves the CmdPkt alone so the caller can reuse it.
Arguments:
CmdPkt -- A ptr to the command packet.
CompletionArg - Unused.
Return Value:
None.
--*/
{
return;
}
VOID
FrsCompleteSynchronousCmdPkt(
IN PCOMMAND_PACKET CmdPkt,
IN PVOID CompletionArg
)
/*++
Routine Description:
This is an Frs Command packet completion routine that
Signals the Wait Event for a synchronous cmd request.
It leaves the CmdPkt alone so the caller can reuse it.
Arguments:
CmdPkt -- A ptr to the command packet.
CompletionArg - Unused.
Return Value:
None.
--*/
{
FRS_ASSERT(HANDLE_IS_VALID(CmdPkt->WaitEvent));
SetEvent(CmdPkt->WaitEvent);
//
// A ctx switch to the waiter could occur at this point. The waiter could
// free the packet. So no further refs to the packet are allowed.
//
return;
}
VOID
FrsInitializeRequestCount(
IN PFRS_REQUEST_COUNT RequestCount
)
/*++
Routine Description:
Initializes a RequestCount for use.
Arguments:
RequestCount - Supplies a pointer to a RequestCount structure to initialize
Return Value:
ERROR_SUCCESS if successful
Win32 error code otherwise.
--*/
{
ULONG Status;
RequestCount->Count = 0;
RequestCount->Status = 0;
InitializeCriticalSection(&RequestCount->Lock);
RequestCount->Event = FrsCreateEvent(TRUE, FALSE);
}
VOID
FrsDeleteRequestCount(
IN PFRS_REQUEST_COUNT RequestCount
)
/*++
Routine Description:
Releases resources used by a RequestCount.
Arguments:
RequestCount - Supplies a pointer to a RequestCount structure to delete
Return Value:
None.
--*/
{
ULONG WStatus;
if (RequestCount != NULL) {
if (HANDLE_IS_VALID(RequestCount->Event)) {
if (!CloseHandle(RequestCount->Event)) {
WStatus = GetLastError();
DPRINT_WS(0, "ERROR: Close event handle failed", WStatus);
DeleteCriticalSection(&RequestCount->Lock);
return;
}
DeleteCriticalSection(&RequestCount->Lock);
}
//
// Zero memory to catch errors.
//
ZeroMemory(RequestCount, sizeof(FRS_REQUEST_COUNT));
}
}
ULONG
FrsWaitOnRequestCount(
IN PFRS_REQUEST_COUNT RequestCount,
IN ULONG Timeout
)
{
DWORD WStatus;
Retry:
if (RequestCount->Count > 0) {
WStatus = WaitForSingleObject(RequestCount->Event, Timeout);
CHECK_WAIT_ERRORS(3, WStatus, 1, ACTION_RETURN);
}
//
// Lock the queue and check again.
//
EnterCriticalSection(&RequestCount->Lock);
if (RequestCount->Count > 0) {
//
// Somebody got here before we did, drop the lock and retry
//
LeaveCriticalSection(&RequestCount->Lock);
goto Retry;
}
LeaveCriticalSection(&RequestCount->Lock);
return(ERROR_SUCCESS);
}
DWORD
FrsRtlInitializeList(
PFRS_LIST List
)
/*++
Routine Description:
Initializes an interlocked list for use.
Arguments:
List - Supplies a pointer to an FRS_LIST structure to initialize
Return Value:
ERROR_SUCCESS if successful
--*/
{
DWORD Status;
InitializeListHead(&List->ListHead);
InitializeCriticalSection(&List->Lock);
List->Count = 0;
List->ControlCount = 0;
List->Control = List;
return(ERROR_SUCCESS);
}
VOID
FrsRtlDeleteList(
PFRS_LIST List
)
/*++
Routine Description:
Releases all resources used by an interlocked list.
Arguments:
List - supplies the List to be deleted
Return Value:
None.
--*/
{
DeleteCriticalSection(&List->Lock);
//
// Zero the memory in order to cause grief to people who try
// and use a deleted list.
//
ZeroMemory(List, sizeof(FRS_LIST));
}
PLIST_ENTRY
FrsRtlRemoveHeadList(
IN PFRS_LIST List
)
/*++
Routine Description:
Removes the item at the head of the interlocked list.
Arguments:
List - Supplies the list to remove an item from.
Return Value:
Pointer to list entry removed from the head of the list.
NULL if the list is empty.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlRemoveHeadList:"
PLIST_ENTRY Entry;
PFRS_LIST Control = List->Control;
if (List->ControlCount == 0) {
return NULL;
}
//
// Lock the list and try to remove something
//
EnterCriticalSection(&Control->Lock);
if (Control->ControlCount == 0) {
//
// Somebody got here before we did, drop the lock and return null
//
LeaveCriticalSection(&Control->Lock);
return NULL;
}
FRS_ASSERT(!IsListEmpty(&List->ListHead));
Entry = RemoveHeadList(&List->ListHead);
//
// Decrement count.
//
List->Count--;
Control->ControlCount--;
LeaveCriticalSection(&Control->Lock);
return(Entry);
}
VOID
FrsRtlInsertHeadList(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Inserts the item at the head of the interlocked list.
Arguments:
List - Supplies the list to insert the item on.
Entry - The entry to insert.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
//
// Lock the list and insert at head.
//
EnterCriticalSection(&Control->Lock);
FrsRtlInsertHeadListLock(List, Entry);
LeaveCriticalSection(&Control->Lock);
return;
}
PLIST_ENTRY
FrsRtlRemoveTailList(
IN PFRS_LIST List
)
/*++
Routine Description:
Removes the item at the tail of the interlocked list.
Arguments:
List - Supplies the list to remove an item from.
Return Value:
Pointer to list entry removed from the tail of the list.
NULL if the list is empty.
--*/
{
#undef DEBSUB
#define DEBSUB "FrsRtlRemoveTailList:"
PLIST_ENTRY Entry;
PFRS_LIST Control = List->Control;
if (Control->ControlCount == 0) {
return NULL;
}
//
// Lock the list and try to remove something
//
EnterCriticalSection(&Control->Lock);
if (Control->ControlCount == 0) {
//
// Somebody got here before we did, drop the lock and return null
//
LeaveCriticalSection(&Control->Lock);
return NULL;
}
FRS_ASSERT(!IsListEmpty(&List->ListHead));
Entry = RemoveTailList(&List->ListHead);
//
// Decrement count.
//
List->Count--;
Control->ControlCount--;
LeaveCriticalSection(&Control->Lock);
return(Entry);
}
VOID
FrsRtlInsertTailList(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Inserts the item at the tail of the interlocked list.
Arguments:
List - Supplies the list to insert the item on.
Entry - The entry to insert.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
//
// Lock the list and insert at tail.
//
EnterCriticalSection(&Control->Lock);
FrsRtlInsertTailListLock(List, Entry);
LeaveCriticalSection(&Control->Lock);
return;
}
VOID
FrsRtlRemoveEntryList(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Removes the entry from the interlocked list. The entry must be on the
given list since we use the lock in the FRS_LIST to synchronize access.
Arguments:
List - Supplies the list to remove an item from.
Entry - The entry to remove.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
//
// Lock the list and try to remove entry
//
EnterCriticalSection(&Control->Lock);
FrsRtlRemoveEntryListLock(List, Entry);
LeaveCriticalSection(&Control->Lock);
return;
}
VOID
FrsRtlRemoveEntryListLock(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Removes the entry from the interlocked list. The entry must be on the
given list.
The caller already has the list lock.
Arguments:
List - Supplies the list to remove an item from.
Entry - The entry to remove.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
//
// List better not be empty.
//
FRS_ASSERT(!IsListEmpty(&List->ListHead));
RemoveEntryListB(Entry);
//
// Decrement count.
//
List->Count--;
Control->ControlCount--;
return;
}
VOID
FrsRtlInsertHeadListLock(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Inserts the item at the head of the interlocked list.
The caller has acquired the lock.
Arguments:
List - Supplies the list to insert the item on.
Entry - The entry to insert.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
InsertHeadList(&List->ListHead, Entry);
List->Count++;
Control->ControlCount++;
return;
}
VOID
FrsRtlInsertTailListLock(
IN PFRS_LIST List,
IN PLIST_ENTRY Entry
)
/*++
Routine Description:
Inserts the item at the tail of the interlocked list.
The caller has acquired the lock.
Arguments:
List - Supplies the list to insert the item on.
Entry - The entry to insert.
Return Value:
None.
--*/
{
PFRS_LIST Control = List->Control;
InsertTailList(&List->ListHead, Entry);
List->Count++;
Control->ControlCount++;
return;
}