IIdleTask Class Reference

#include <IIdleTask.h>

Inheritance diagram for IIdleTask:

Public Types
enum	{ kDefaultIID = IID_IIDLETASK }
enum	{ kEndOfTime = ~(uint32)0, kOnFlagChange = ~(uint32)1, kNextEventCycle = ~(uint32)2 }
enum	{ kMaxTaskNameLength = 1023 }

Public Member Functions
virtual uint32	RunTask (uint32 appFlags, IdleTimer *timeCheck)=0
virtual void	InstallTask (uint32 millisecsBeforeFirstRun)=0
virtual void	UninstallTask ()=0
virtual const char *	TaskName ()=0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

An IIdleTask is an element of the IIdleTaskMgr's priority queue of tasks that have an opportunity to run each pass through the main event loop.

Member Enumeration Documentation

anonymous enum

Enumerator
kEndOfTime	Task should be removed imediately from the IdleTaskMgr
kOnFlagChange	Don't call again until the app state has changed
kNextEventCycle	Yield for at least one cycle of the event loop which allows the cmd queue to be flushed

Member Function Documentation

virtual void IIdleTask::InstallTask ( uint32  millisecsBeforeFirstRun )

pure virtual

InstallTask would be called by whatever code wants to get this task started. Such code may look like this:

InterfacePtr<IIdleTask> myTask(...);

myTask->InstallTask(100);

You should call the IdleTaskMgr's AddTask method in addition to other startup chores for this task.

Parameters

millisecsBeforeFirstRun

- The number of milliseconds to wait before running this task the first time.

See Also

IdleTaskMgr

Implemented in CIdleTaskThread, and CIdleTask.

virtual uint32 IIdleTask::RunTask ( uint32  appFlags, IdleTimer *  timeCheck  )

pure virtual

Will perform its task and then relinquish control until it is called again. See CIdleTaskThread.h if this API is inconvenient for the task at hand.

Parameters

appFlags	- Informs this method of the current state of the app see IIdleTaskMgr::ApplicationStateFlags
timeCheck	- A callback method that should be called periodically during long tasks to see whether RunTask has run out of time and needs to return.

Returns

- The number of milliseconds to sleep before running again.

o Returning kEndOfTime means that this task will be removed from the IdleTaskMgr–without calling its UninstallTask method. Hence, you should do whatever other chores you do in UninstallTask before returning this value.

o If this task's UninstallTask method is called before RunTask returns, then the return value for RunTask will be ignored.

o Returning kOnFlagChange suspends this task until appFlags changes. At which point it will be called again ASAP. RunTask can continue to return kOnFlagChange as long as it doesn't like the current appFlags.

See Also

IdleTaskMgr

CIdleTaskThread

IIdleTaskMgr::ApplicationStateFlags

Implemented in CIdleTaskThread, PnlTrvIdleTask, and CusDtLnkLinkResourceStateUpdaterIdleTask.

virtual const char* IIdleTask::TaskName ( )

pure virtual

A task's name is simply a C string that is used internally by the IdleTaskMgr. It is used for debugging and logging purposes and need not be unique among tasks although this would certainly be more helpful. NOTE: Eventually this will probably be a parameter passed to IdleTaskMgr::AddTask.

Returns

- The string returned is immediately copied.

See Also

IdleTaskMgr

Implemented in CIdleTaskThread, PnlTrvIdleTask, CIdleTask, and CusDtLnkLinkResourceStateUpdaterIdleTask.

virtual void IIdleTask::UninstallTask ( )

pure virtual

Uninstall would be called by companion code to that which installs the task. Such code may look like this:

InterfacePtr<IIdleTask> myTask(...);

myTask->UninstallTask();

You should call the IdleTaskMgr's RemoveTask method in addition to other cleanup chores for this task. Note that the IdleTaskMgr does NOT call UninstallTask when you return kEndOfTime from your RunTask method–it simply internally removes the task from its queues. However IdleTaskMgr DOES call UninstallTask for any tasks that were not yet removed when its Shutdown method is called. In this situation your UninstallTask must call IIdleTaskMgr::RemoveTask() directly or indirectly or you will hit an assert.

See Also

IdleTaskMgr

Implemented in CIdleTaskThread, and CIdleTask.