sbRequestThreadQueue Class Referenceabstract

#include <sbRequestThreadQueue.h>

Inheritance diagram for sbRequestThreadQueue:
[legend]

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
aRequeststhe 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  )
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
aBatcha 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
aRequestIteman 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: