InDesign SDK  20.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
IIdleTask.h
1 //========================================================================================
2 //
3 // $File$
4 //
5 // Owner: Shawn Sheridan
6 //
7 // $Author$
8 //
9 // $DateTime$
10 //
11 // $Revision$
12 //
13 // $Change$
14 //
15 // Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
16 //
17 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance
18 // with the terms of the Adobe license agreement accompanying it. If you have received
19 // this file from a source other than Adobe, then your use, modification, or
20 // distribution of it requires the prior written permission of Adobe.
21 //
22 //
23 // Idle task mgr (alternative to real threads)
24 //
25 // Purpose:
26 // An IIdleTask is an element of the IIdleTaskMgr's priority queue of tasks
27 // that have an opportunity to run each pass through the main event loop.
28 //
29 // Review Date:
30 //
31 //========================================================================================
32 
33 #ifndef __IIdleTask__
34 #define __IIdleTask__
35 
36 #include "IPMUnknown.h"
37 #include "ShuksanID.h"
38 
39 /*
40  #include "HelperInterface.h"
41  #include "IIdleTask.h"
42  #include "ShuksanID.h"
43  #include "IIdleTaskMgr.h"
44  #include "ISession.h"
45 
46  class MyIdleTask : public IIdleTask
47  {
48  public:
49  MyIdleTask(IPMUnknown *boss);
50  ~MyIdleTask();
51  uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)());
52  void InstallTask(uint32 millisecsBeforeFirstRun);
53  void UninstallTask();
54  const char* TaskName();
55  private:
56  bool InappropriateState(uint32 flags);
57  //...
58 
59 
60  };
61 
62  DEFINE_HELPER_METHODS(MyIdleTask)
63 
64  MyIdleTask::MyIdleTask(IPMUnknown *boss) : HELPER_METHODS_INIT(boss)
65  {
66  }
67 
68  const char* MyIdleTask::TaskName()
69  {
70  return "MyIdleTask: used to do cool things";
71  }
72 
73  void MyIdleTask::InstallTask(uint32 millisecsBeforeFirstRun)
74  {
75  //perhaps other chores
76  InterfacePtr<IIdleTaskMgr> idleTaskMgr(GetExecutionContextSession(), UseDefaultIID());
77  if(idleTaskMgr) idleTaskMgr->AddTask(this, millisecsBeforeFirstRun);
78  }
79 
80 
81 //one time task
82  uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
83  {
84  if( InappropriateState(schedulerFlags))
85  return kOnFlagChange;
86  DoOneTimeThing();
87  //Clean up as UninstallTask won't be called
88  return kEndOfTime;
89  }
90 
91 //periodic task
92 //Note this is not drift free. You would have to
93 //keep track of the time yourself and adjust the
94 //return value downward to make up for the fact
95 //that RunTask calls are always overdue.
96  uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
97  {
98  if( InappropriateState(schedulerFlags))
99  return kOnFlagChange;
100  DoPeriodicThing();
101  return 1000; //Call me again in 1 second.
102  }
103 
104 //lengthy interruptable one time task: Substitute a sleep
105 //value for kEndOfTime for a lengthy interruptable periodic task
106  uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
107  {
108  if( InappropriateState(schedulerFlags))
109  return kOnFlagChange;
110 
111  do{
112  DoSomething( fThingsLeftToDo);
113  }while( --fThingsLeftToDo && timeCheck() > 0);
114 
115  return fThingsLeftToDo ? 0 : kEndOfTime;
116  }
117 
118 //adjustable period, periodic task
119  uint32 RunTask( uint32 schedulerFlags, uint32 (*timeCheck)())
120  {
121  if( InappropriateState(schedulerFlags))
122  return kOnFlagChange;
123  DoPeriodicThing();
124  return schedulerFlags & kBackground ? 5000 : 1000;
125  }
126 
127 
128 
129  void MyIdleTask::UninstallTask()
130  {
131  //perhaps other chores
132  InterfacePtr<IIdleTaskMgr> idleTaskMgr(GetExecutionContextSession(), UseDefaultIID());
133  if(idleTaskMgr) idleTaskMgr->RemoveTask(this);
134  }
135 
136 */
137 
138 /* @ashishja
139  This enumerator is used in order to check whether idle task needs to be stopped
140  due to a specific reason. More values can be added here as per the need evolves.
141  All these types may not be supported for IdleTimer derived impls. So the derived impls
142  need to handle the unsupported types as per their requirement gracefully .
143 */
144 enum IdleTimerCompletionType
145 {
146  kTimeout, /* checks whether only timout has occured */
147  kEventPending, /* checks whether some event is pending */
148  kDefault /* checks for all possible reasons to stop the idle task */
149 };
150 
154 class IdleTimer{
155  public:
165  virtual uint32 operator()(IdleTimerCompletionType completionType = IdleTimerCompletionType::kDefault) = 0;
166 
168  virtual void LogString( const char*) = 0;
169 };
170 
174 class IIdleTask : public IPMUnknown
175 {
176  public:
177  enum { kDefaultIID = IID_IIDLETASK };
178 
179  enum {
181  kEndOfTime = ~(uint32)0,
183  kOnFlagChange = ~(uint32)1,
185  kNextEventCycle = ~(uint32)2};
186 
211  virtual uint32 RunTask( uint32 appFlags, IdleTimer* timeCheck) = 0;
212  //virtual uint32 RunTask( uint32 appFlags, uint32 (*timeCheck)()) = 0;
213 
226  virtual void InstallTask(uint32 millisecsBeforeFirstRun) = 0;
227 
246  // Should UninstallTask return RemoveTask's return value?
247  virtual void UninstallTask() = 0;
248 
249  enum { kMaxTaskNameLength = 1023}; //1024 if you include the trailing '\0'
250 
260  virtual const char* TaskName() = 0;
261 };
262 
263 
264 #endif // __IIdleTask__