IIdleTask.h

//========================================================================================
// 
// $File$
// 
// Owner: Shawn Sheridan
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
// 
// Idle task mgr (alternative to real threads)
// 
// Purpose:
// 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.
// 
// Review Date:
// 
//========================================================================================

#ifndef __IIdleTask__
#define __IIdleTask__

#include "IPMUnknown.h"
#include "ShuksanID.h"

/*
 #include "HelperInterface.h"
 #include "IIdleTask.h"
 #include "ShuksanID.h"
 #include "IIdleTaskMgr.h"
 #include "ISession.h"

 class MyIdleTask : public IIdleTask
 {
 public:
 MyIdleTask(IPMUnknown *boss);
 ~MyIdleTask();
 uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)());
 void InstallTask(uint32 millisecsBeforeFirstRun);
 void UninstallTask();
 const char* TaskName();
 private:
 bool InappropriateState(uint32 flags);
 //...

 
 };

 DEFINE_HELPER_METHODS(MyIdleTask)

 MyIdleTask::MyIdleTask(IPMUnknown *boss) : HELPER_METHODS_INIT(boss)
 {
 }

 const char* MyIdleTask::TaskName()
 {
 return "MyIdleTask: used to do cool things";
 }

 void MyIdleTask::InstallTask(uint32 millisecsBeforeFirstRun)
 {
 //perhaps other chores
 InterfacePtr<IIdleTaskMgr> idleTaskMgr(GetExecutionContextSession(), UseDefaultIID());
 if(idleTaskMgr) idleTaskMgr->AddTask(this, millisecsBeforeFirstRun);
 }


//one time task
 uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
 {
 if( InappropriateState(schedulerFlags))
 return kOnFlagChange;
 DoOneTimeThing();
 //Clean up as UninstallTask won't be called
 return kEndOfTime;
 }

//periodic task
//Note this is not drift free. You would have to
//keep track of the time yourself and adjust the
//return value downward to make up for the fact
//that RunTask calls are always overdue.
 uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
 {
 if( InappropriateState(schedulerFlags))
 return kOnFlagChange;
 DoPeriodicThing();
 return 1000; //Call me again in 1 second.
 }

//lengthy interruptable one time task: Substitute a sleep
//value for kEndOfTime for a lengthy interruptable periodic task
 uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
 {
 if( InappropriateState(schedulerFlags))
 return kOnFlagChange;

 do{
 DoSomething( fThingsLeftToDo);
 }while( --fThingsLeftToDo && timeCheck() > 0);
 
 return fThingsLeftToDo ? 0 : kEndOfTime;
 }

//adjustable period, periodic task
 uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
 {
 if( InappropriateState(schedulerFlags))
 return kOnFlagChange;
 DoPeriodicThing();
 return schedulerFlags & kBackground ? 5000 : 1000;
 }



 void MyIdleTask::UninstallTask()
 {
 //perhaps other chores
 InterfacePtr<IIdleTaskMgr> idleTaskMgr(GetExecutionContextSession(), UseDefaultIID());
 if(idleTaskMgr) idleTaskMgr->RemoveTask(this);
 }
 
*/

/* @ashishja
 This enumerator is used in order to check whether idle task needs to be stopped 
 due to a specific reason. More values can be added here as per the need evolves.
 All these types may not be supported for IdleTimer derived impls. So the derived impls
 need to handle the unsupported types as per their requirement gracefully .
*/
enum IdleTimerCompletionType
{
 kTimeout, /* checks whether only timout has occured */
 kEventPending, /* checks whether some event is pending */
 kDefault /* checks for all possible reasons to stop the idle task */
};

class IdleTimer{
 public:
 virtual uint32 operator()(IdleTimerCompletionType completionType = IdleTimerCompletionType::kDefault) = 0;

 virtual void LogString( const char*) = 0;
};

class IIdleTask : public IPMUnknown
{
 public:
 enum { kDefaultIID = IID_IIDLETASK };

 enum { 
 kEndOfTime = ~(uint32)0, 
 kOnFlagChange = ~(uint32)1, 
 kNextEventCycle = ~(uint32)2};

 virtual uint32 RunTask( uint32 appFlags, IdleTimer* timeCheck) = 0;
 //virtual uint32 RunTask( uint32 appFlags, uint32 (*timeCheck)()) = 0;
 
 virtual void InstallTask(uint32 millisecsBeforeFirstRun) = 0;

 // Should UninstallTask return RemoveTask's return value?
 virtual void UninstallTask() = 0;

 enum { kMaxTaskNameLength = 1023}; //1024 if you include the trailing '\0'
 
 virtual const char* TaskName() = 0;
};


#endif // __IIdleTask__