queue.h File Reference

Definitions for the queueing functions. More...

Go to the source code of this file.

Defines
#define	QueueIsStalled(_Queue_)   (_Queue_->IsStalled ? 1 : 0)
#define	QueueIsDropping(_Queue_)   (_Queue_->IsDropping ? 1 : 0)
Typedefs
typedef NTSTATUS(*	PCBMDRIVER_STARTIO )(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp)
typedef QUEUE	QUEUE
	A QUEUE object A QUEUE object is an object which can be used to queue IRPs for processing. This QUEUE object is optimized for being polled from an own worker thread. Anyway, a concept called FastStart is also implemented, which allows some IRPs to be completed immediately, without being queued, if no IRP is executed yet and the caller has stated that he wants this IRP to be started fast if possible.
typedef QUEUE *	PQUEUE
	A QUEUE object A QUEUE object is an object which can be used to queue IRPs for processing. This QUEUE object is optimized for being polled from an own worker thread. Anyway, a concept called FastStart is also implemented, which allows some IRPs to be completed immediately, without being queued, if no IRP is executed yet and the caller has stated that he wants this IRP to be started fast if possible.
Functions
VOID	QueueInit (PQUEUE Queue, PCBMDRIVER_STARTIO DriverStartIo)
	Initialize a QUEUE object.
NTSTATUS	QueueCompleteIrp (PQUEUE Queue, PIRP Irp, NTSTATUS StatusCode, ULONG_PTR Information)
	Complete an IRP which is on a QUEUE.
NTSTATUS	QueueStartPacket (PQUEUE Queue, PIRP Irp, BOOLEAN FastStart, PDEVICE_OBJECT Fdo)
	Insert an IRP into a QUEUE object.
NTSTATUS	QueuePoll (PQUEUE Queue, PDEVICE_OBJECT Fdo)
	Poll the QUEUE.
NTSTATUS	QueueSignal (PQUEUE Queue)
	Signal to the QUEUE need for processing.
NTSTATUS	QueueCleanup (PQUEUE Queue, PFILE_OBJECT FileObject)
	Process an IRP_MJ_CLEANUP on the QUEUE.
BOOLEAN	QueueShouldCancelCurrentIrp (PQUEUE Queue)
	Should the current IRP be cancelled?

---

Detailed Description

Definitions for the queueing functions.

**************************************************************

Author:

Spiro Trikaliotis

Version:

Id

queue.h,v 1.3 2006/04/08 13:40:02 trikalio Exp

Definition in file queue.h.

---

Define Documentation

#define QueueIsDropping (  _Queue_   )     (_Queue_->IsDropping ? 1 : 0)

Return: Is the queue currently dropping Definition at line 97 of file queue.h.

#define QueueIsStalled (  _Queue_   )     (_Queue_->IsStalled ? 1 : 0)

Return: Is queue currently stalled Definition at line 94 of file queue.h.

---

Typedef Documentation

typedef NTSTATUS(* PCBMDRIVER_STARTIO)(IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp)

This type specifies a StartIo function for the Queue Definition at line 29 of file queue.h.

---

Function Documentation

NTSTATUS QueueCleanup (  PQUEUE  Queue, PFILE_OBJECT  FileObject )

Process an IRP_MJ_CLEANUP on the QUEUE. Whenever an IRP_MJ_CLEANUP is received by the driver, it has to complete all IRPs that belong to the given file object. This function takes all appropriate IRPs out of the QUEUE and completes them. Parameters: Queue  Pointer to the QUEUE object. FileObject  Pointer to the FILE_OBJECT of which the associated IRPs have to be cancelled. Todo: What if the current IRP is associated to that FILE_OBJECT? Will that one be cancelled separately? Todo: What if the current irp is associated with that FILE_OBJECT? Definition at line 999 of file queue.c. References FUNC_ENTER, QUEUE::IrpQueue, and QueueCompleteIrp(). Referenced by cbm_cleanup().

NTSTATUS QueueCompleteIrp (  PQUEUE  Queue, PIRP  Irp, NTSTATUS  NtStatus, ULONG_PTR  Information )

Complete an IRP which is on a QUEUE. This function completes an IRP which is on a QUEUE object Parameters: Queue  Pointer to the QUEUE object, or NULL if the IRP is on no QUEUE at all. Irp  Pointer to the Irp to be completed NtStatus  The NTSTATUS code which is to be used for the completion Information  The value to give the Information field of the IRP Returns: Returns the given NtStatus Without any further protection, the state which is reported could have changed at the time this function returns! Thus, handle with care. Definition at line 757 of file queue.c. References QUEUE::CurrentIrp, DBG_ASSERT, FUNC_ENTER, and PERF_EVENT_COMPLETEIRP. Referenced by cbm_cleanup(), cbm_createopenclose(), cbm_devicecontrol(), cbm_execute_close(), cbm_execute_createopen(), cbm_execute_devicecontrol(), cbm_execute_readwrite(), cbm_readwrite(), QueueCleanup(), and QueueStartPacket().

VOID QueueInit (  PQUEUE  Queue, PCBMDRIVER_STARTIO  DriverStartIo )

Initialize a QUEUE object. This function initializes a QUEUE object before it can be used by the other Queue...() functions. Parameters: Queue  Pointer to the QUEUE object. DriverStartIo  Pointer to the StartIo function for this queue Definition at line 389 of file queue.c. References QUEUE::DriverStartIo, FUNC_ENTER, FUNC_LEAVE, QUEUE::IrpListHead, QUEUE::IrpListSpinlock, QUEUE::IrpQueue, QUEUE::IsDropping, QUEUE::IsStalled, and QUEUE::NotEmptyEvent. Referenced by AddDeviceCommonInit().

NTSTATUS QueuePoll (  PQUEUE  Queue, PDEVICE_OBJECT  Fdo )

Poll the QUEUE. This function polls the QUEUE object. If there is an IRP in there, the IRP is executed by calling the specified DriverStartIo() function. If there is no IRP, this function just sleeps until there is one. Parameters: Queue  Pointer to the QUEUE object. Fdo  Pointer to the DEVICE_OBJECT on which the Queue is located. This parameter is given to the call of StartIo(). Bug: This function does not perform any synchronization other than what ExInterlockedRemoveHeadList() provides. Because of this, it is not safe to be used directly from a driver. Definition at line 817 of file queue.c. References QUEUE::CurrentIrp, DBG_ASSERT, QUEUE::DriverStartIo, FUNC_ENTER, and QUEUE::NotEmptyEvent. Referenced by cbm_thread().

BOOLEAN QueueShouldCancelCurrentIrp (  PQUEUE  Queue  )

Should the current IRP be cancelled? Find out if the caller of the current IRP is not interested anymore in the result. Parameters: Queue  Pointer to the QUEUE object. This function should be called in the processing of an IRP whenever there is a change that some processing will take some considerable time. An alternative to polling this function is to install a cancel routine. Definition at line 1042 of file queue.c. References QUEUE::CurrentIrp, FUNC_ENTER, and FUNC_LEAVE_BOOLEAN. Referenced by cbmiec_i_raw_read(), cbmiec_i_raw_write(), cbmiec_iec_wait(), and cbmiec_wait_for_listener().

NTSTATUS QueueSignal (  PQUEUE  Queue  )

Signal to the QUEUE need for processing. This function signals the QUEUE object that there is something to be processed. In general, this means that some IRP has been queued. Parameters: Queue  Pointer to the QUEUE object. Definition at line 901 of file queue.c. References FUNC_ENTER, and QUEUE::NotEmptyEvent. Referenced by cbm_stop_thread(), and QueueStartPacket().

NTSTATUS QueueStartPacket (  PQUEUE  Queue, PIRP  Irp, BOOLEAN  FastStart, PDEVICE_OBJECT  Fdo )

Insert an IRP into a QUEUE object. This function inserts an IRP into the given QUEUE object. Parameters: Queue  Pointer to the QUEUE object. Irp  Pointer to the IRP to be queued. FastStart  If this value is TRUE, than this IRP does not last long. Thus, it can be started immediately if the QUEUE is empty. If this value is FALSE, this IRP can take much time, so a fast start is not allowed Fdo  Pointer to the DEVICE_OBJECT. This is only needed if FastStart is TRUE. Returns: If the IRP has been successfully inserted into the QUEUE, this function returns STATUS_PENDING. If the IRP could not be inserted, it returns the status code given by the abortion status. If the queue is in the dropping state, this function does not insert the IRP into the queue, but it immediately completes the IRP with the given abortion status. The return value can be directly used in the dispatch function which calls QueueStartPacket() as the return status. Definition at line 468 of file queue.c. References QUEUE::CurrentIrp, DBG_ASSERT, QUEUE::DriverStartIo, QUEUE::DroppingReturnStatus, FUNC_ENTER, QUEUE::IrpQueue, QUEUE::IsDropping, QueueCompleteIrp(), and QueueSignal(). Referenced by cbm_createopenclose(), cbm_devicecontrol(), and cbm_readwrite().

---