#include <sbRequestThreadQueue.h>

Inheritance diagram for sbRequestThreadQueue:

Classes
class	Batch

Public Types
enum	{ USER_REQUEST_TYPES = 0x20000000, REQUEST_TYPE_NOT_SET = 0, REQUEST_THREAD_START = 1, REQUEST_THREAD_STOP = 2 }

Public Member Functions
	NS_IMETHOD_ (nsrefcnt) AddRef(void)

	NS_IMETHOD_ (nsrefcnt) Release(void)

	sbRequestThreadQueue ()

virtual	~sbRequestThreadQueue ()

nsresult	Start ()

nsresult	Stop ()

nsresult	BatchBegin ()

nsresult	BatchEnd ()

nsresult	PushRequest (sbRequestItem *aRequestItem)

nsresult	PopBatch (Batch &aBatch)

nsresult	ClearRequests ()

nsresult	CancelRequests ()

bool	CheckAndResetRequestAbort ()

bool	IsHandlingRequests () const

bool	IsRequestAbortActive () const

PRMonitor *	GetStopWaitMonitor () const

Protected Member Functions
nsresult	ClearRequestsNoLock (Batch &aRequests)

virtual void	CompleteRequests ()

Protected Attributes
PRLock *	mLock

PRInt32	mBatchDepth

PRMonitor *	mStopWaitMonitor

bool	mAbortRequests

bool	mIsHandlingRequests

bool	mThreadStarted

bool	mStopProcessing

Friends
class	sbRTQAddedEvent

class	sbRTQIsBatchable

class	sbAutoRequestHandling

Detailed Description

This class implements a mechanism to allow processing of requests off the main thread. PushRequest places requests on the queue. BatchBegin and BatchEnd mark the start and end of batches. Batches of requests are processed via the pure virtual method ProcessBatch. Derived classes implement this to do work specific to their needs. Start is called to start the request thread and Stop is used to stop the request thread.

sbRequestItem is owned by sbRequestThreadQueue when pushed onto the queue. A reference is added. When PopBatch is called, ownership is transferred to the Batch object passed in. The sbRequestItem object holds a reference and releases it when the Batch is destroyed or the item is erased via erase or clear methods. Batch's destructor calls clear.

Definition at line 65 of file sbRequestThreadQueue.h.

Member Enumeration Documentation

anonymous enum

Enumerator
USER_REQUEST_TYPES	Request types below this value are reserved for use by this class
REQUEST_TYPE_NOT_SET	Used to signal that a request type has not be set
REQUEST_THREAD_START	Request type of the request sent as the first request
REQUEST_THREAD_STOP	Request type of the request sent as the last request to signal the thread to shutdown

Definition at line 221 of file sbRequestThreadQueue.h.

Constructor & Destructor Documentation

sbRequestThreadQueue::sbRequestThreadQueue ( )

Performs simple initialization.

Initialize the various data members. We initialize mCurrentBatchId to 1 as requests not belonging to a batch have a batch ID of 0.

Definition at line 199 of file sbRequestThreadQueue.cpp.

sbRequestThreadQueue::~sbRequestThreadQueue ( )

virtual

Definition at line 217 of file sbRequestThreadQueue.cpp.

Member Function Documentation

nsresult sbRequestThreadQueue::BatchBegin ( )

Marks the start of a batch

Definition at line 229 of file sbRequestThreadQueue.cpp.

nsresult sbRequestThreadQueue::BatchEnd ( )

Marks the end of a batch

Definition at line 241 of file sbRequestThreadQueue.cpp.

nsresult sbRequestThreadQueue::CancelRequests ( )

Sets the abort flag and clears cany pending requests. This will release all request item references owned by the request queue.

Definition at line 579 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

bool sbRequestThreadQueue::CheckAndResetRequestAbort ( )

Returns whether an abort is active and clears the abort flag. We want to clear the flag since all usage patterns will need to inspect the state and if locked clear the flag. This eliminates the issue of checking and then some other code checking and then both thinking an abort is in progress. This MUST only be called from the request processing thread.

Definition at line 611 of file sbRequestThreadQueue.cpp.

nsresult sbRequestThreadQueue::ClearRequests ( )

Clears the request queue. This will release all request item references owned by the request queue.

Definition at line 553 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

nsresult sbRequestThreadQueue::ClearRequestsNoLock ( Batch & aRequests )

protected

Performs simple cleanup of the requests queue without locking and returns the cleared requests as an array. It is the caller's responsibility to lock mLock

Parameters

aRequests the requests that were cleared

Definition at line 536 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

virtual void sbRequestThreadQueue::CompleteRequests ( )

inlineprotectedvirtual

Signals completion of the current batch of requests

Definition at line 404 of file sbRequestThreadQueue.h.

Here is the caller graph for this function:

PRMonitor* sbRequestThreadQueue::GetStopWaitMonitor ( ) const

inline

Returns the monitor used for signaling process stopping. Ownership is retained by "this" and caller should not delete this pointer. This is used so that users can block and wait until an abort request or stop request has been been processed. Care should be taken when using this on the main thread.

Definition at line 329 of file sbRequestThreadQueue.h.

bool sbRequestThreadQueue::IsHandlingRequests ( ) const

inline

This returns whether the RequestThreadQueue is running currently.

Definition at line 305 of file sbRequestThreadQueue.h.

bool sbRequestThreadQueue::IsRequestAbortActive ( ) const

inline

This simply returns whether an abort has been signaled. Ideally use checkAndResetRequestAbort unless there is a specific reason not to.

Definition at line 316 of file sbRequestThreadQueue.h.

sbRequestThreadQueue::NS_IMETHOD_ ( nsrefcnt )

nsresult sbRequestThreadQueue::PopBatch ( Batch & aBatch )

Returns the next batch. Request items returned in aBatch are no longer owned by the request queue but belong to aBatch.

Parameters

aBatch a collection of sbRequestItem derived objects

Definition at line 484 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

nsresult sbRequestThreadQueue::PushRequest ( sbRequestItem * aRequestItem )

Pushes a request entry onto the request queue. This will add an owning reference to aRequestItem.

Parameters

aRequestItem an object derived from sbRequestItem

Definition at line 451 of file sbRequestThreadQueue.cpp.

Here is the caller graph for this function:

nsresult sbRequestThreadQueue::Start ( )

Starts the request queue processing

Definition at line 285 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

nsresult sbRequestThreadQueue::Stop ( )

This stops the request processing thread. It returns immediately and does not wait for the request thread to shutdown.. The aShutdownAction is used to perform any post cleanup work. This action is called after the thread has actually shutdown.

Definition at line 327 of file sbRequestThreadQueue.cpp.

Here is the call graph for this function:

Friends And Related Function Documentation

friend class sbAutoRequestHandling

friend

Needs access to the StartRequests and CompleteRequests. This is an internal utility class.

Definition at line 555 of file sbRequestThreadQueue.h.

friend class sbRTQAddedEvent

friend

Our event object used to dispatch event requests

Definition at line 544 of file sbRequestThreadQueue.h.

friend class sbRTQIsBatchable

friend

Needs access to IsRequestBatchable which otherwise doesn't need to be public. This is an internal utility class

Definition at line 549 of file sbRequestThreadQueue.h.

Member Data Documentation

bool sbRequestThreadQueue::mAbortRequests

protected

Flag that signals we're aborting all requests. Any new requests are ignored while this flag is active.

Definition at line 386 of file sbRequestThreadQueue.h.

PRInt32 sbRequestThreadQueue::mBatchDepth

protected

Tracks batch depth for begin and end calls

Definition at line 374 of file sbRequestThreadQueue.h.

bool sbRequestThreadQueue::mIsHandlingRequests

protected

Flag that indicates we're currently handling a request

Definition at line 391 of file sbRequestThreadQueue.h.

PRLock* sbRequestThreadQueue::mLock

protected

Thread usage summary: The state of this object is protected by the the mLock lock. Accessed by indicator: MT - Thread pushing requests on to queue. Usually this is the main thread, but it could be any thread including the RT. ST - Thread that calls Start, usually will be the the main thread. RT - Thread that process requests mRequestQueue - MT/CT Modified mBatchDepth - MT Write, RT Read mLock - Any thread, protects the state of the object mStopProcessing - ST Written, MT/RT Read mAbortRequests - Can be modified by any thread, read from RT and MT mIsHandlingRequests - RT Written, Read from any thread canceling requests mCurrentBatchId - ST Written, MT - Read/Written

Not protected by mlock, only used by the request thread or only the thread calling Start and Stop

calling start stop mActions - ST Written, RT/MT Used, mThreadStarted - ST written in Start and Stop mReqAddedEvent - ST Create, MT Read mShutdownAction - ST Written, RT used mStopWaitMonitor - Used from any thread, created and destroyed from ST mThread - ST Create, MT calls shutdown This protects the state of the sbRequestThreadProc. This lock needs to be acquired before changing any data member

Definition at line 369 of file sbRequestThreadQueue.h.

bool sbRequestThreadQueue::mStopProcessing

protected

Flag that signals we're stopping request processing

Definition at line 423 of file sbRequestThreadQueue.h.

PRMonitor* sbRequestThreadQueue::mStopWaitMonitor

protected

Monitor to use to signal process stopping to external sources.

Definition at line 379 of file sbRequestThreadQueue.h.

bool sbRequestThreadQueue::mThreadStarted

protected

Used by Start and Stop to ensure callers don't call Start multiple times or erroneously call Stop when not started or stop multiple times.

Definition at line 418 of file sbRequestThreadQueue.h.

The documentation for this class was generated from the following files:

/home/martin/dev/nightingale-hacking/components/devices/device/src/sbRequestThreadQueue.h
/home/martin/dev/nightingale-hacking/components/devices/device/src/sbRequestThreadQueue.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation