CTR Pia  4.11.3
Game Communication Engine
common_Job.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_Job.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/common/common_definitions.h>
18 #include <pia/common/common_ListNode.h>
19 #include <pia/common/common_Time.h>
20 
21 namespace nn
22 {
23 namespace pia
24 {
25 namespace common
26 {
27 
28 /*!
29 @cond PRIVATE
30 @brief Represents the base class for jobs.
31 
32 @details To use job-related features, override the pure virtual function <tt>ExecuteCore</tt> in the derived class.
33 
34 */
35 class Job : public RootObject
36 {
37 public:
38 /*!
39 @brief Enumerates job states.
40 */
41  enum State
42  {
43  STATE_INITIAL, //! Indicates the state immediately after a job instance was created.
44  STATE_WAITING, //! Indicates the job is currently waiting. The job does not run until the specified time has elapsed.
45  STATE_SUSPEND, //! Indicates the job has been suspended.
46  STATE_READY, //! Indicates the job can be executed.
47  STATE_RUNNING, //! Indicates the job is currently executing.
48  STATE_COMPLETE, //! Indicates that job execution has completed.
49  STATE_MAX //! Provided as a sentinel to indicate the last <tt>State</tt> enumerated type.
50  };
51 
52 
53 /*!
54 @brief Instantiates the object.
55 
56 @details Because this class includes pure virtual functions, you must create a class that inherits this base class to use job-related features.
57 
58 */
59  Job();
60 
61 
62 /*!
63 @brief Destroys the object.
64 */
65  virtual ~Job();
66 
67 
68 /*!
69 @brief Resets a job so it can be reused.
70 
71 @details Call this function when you want to reuse a job that has been executed by the scheduler.
72 Calling this member function is equivalent to placing the instance in the same state as immediately after the constructor is called.
73 The function asserts if it is called on a job whose status is <tt>STATE_RUNNING</tt> (if it is called while <tt>ExecuteCore</tt> is running).
74 The function succeeds if it is called in other states, but a warning message is output if it is called in any state other than <tt>STATE_INITIAL</tt> or <tt>STATE_COMPLETE</tt>.
75 
76 
77 */
78  virtual void Reset(bool isCheck = true);
79 
80 
81 /*!
82 @brief Puts a job currently in initial status (<tt>STATE_INITIAL</tt>) in executable status (<tt>STATE_READY</tt>).
83 
84 @details This function asserts if it is called when the job is in any other state.
85 
86 @param[in] isBackground Specify <tt>true</tt> if using <tt>BackgroundScheduler</tt> to run this function in another thread.
87 */
88  void Ready(bool isBackground = false);
89 
90 
91 /*!
92 @brief Puts a job currently in suspended status (<tt>STATE_SUSPEND</tt>) in executable status (<tt>STATE_READY</tt>).
93 
94 @details This function asserts if it is called when the job is in any other state.
95 
96 @param[in] isBackground Specify <tt>true</tt> if using <tt>BackgroundScheduler</tt> to run this function in another thread.
97 */
98  void Resume(bool isBackground = false);
99 
100 
101 /*!
102 @brief Stops the job.
103 
104 @details The functionality is the same as the <tt>Reset</tt> function, except that it does not output warnings.
105 */
106  void Cancel()
107  {
108  Reset(false);
109  }
110 
111 
112 /*!
113 @brief Gets the job's state.
114 
115 @return Returns the job's current state.
116 */
117  State GetState() const;
118 
119 
120 /*!
121 @brief Gets whether the job is currently running.
122 @return Returns <tt>true</tt> if the job's status is <tt>WAITING</tt>, <tt>READY</tt>, <tt>RUNNING</tt>, or <tt>SUSPEND</tt>.
123 */
124  bool IsRunning() const;
125 
126 
127 /*!
128 @brief Gets whether the job is running in the foreground.
129 @return Returns <tt>true</tt> if the job's state is <tt>WAITING</tt>, <tt>READY</tt>, or <tt>RUNNING</tt> in the foreground.
130 */
131  bool IsForeground() const;
132 
133 /*!
134 @brief Gets whether the job is running in the background.
135 @return Returns <tt>true</tt> if the job's state is <tt>WAITING</tt>, <tt>READY</tt>, or <tt>RUNNING</tt> in the background.
136 */
137  bool IsBackground() const;
138 
139 
140 /*!
141 @brief Gets how many times the job has been run.
142 
143 @return Returns <tt>0</tt> if the job has never been run by calling the <tt>Execute</tt> function.
144 The counter increments after the <tt>ExecuteCore</tt> function is called.
145 */
146  u32 GetExecutedCount() const
147  {
148  return m_ExecutedCount;
149  }
150 
151 
152 /*!
153 @brief Gets the next time when a job in a waiting state will be executed.
154 
155 @return Returns the time in ticks.
156 */
157  const Time& GetExecutionTime() const
158  {
159  return m_ExecutionTime;
160  }
161 
162 
163 /*!
164 @cond PRIVATE
165 @brief Executes a job.
166 
167 @details This member function is meant to be called by the scheduler.
168 Applications should not call this function directly.
169 */
170  void Execute(bool isBackground);
171  //! @endcond
172 
173 
174 /*!
175 @cond PRIVATE
176 @brief Gets the offset to the list node.
177 */
178  static s32 GetListNodeOffset()
179  {
180  return offsetof(Job, m_ListNode);
181  }
182  //! @endcond
183 
184 
185 /*!
186 @brief Indicates the type of execution result.
187 */
189  {
190  EXECUTE_STATE_CONTINUE, //! Indicates execution is not complete. Continue execution.
191  EXECUTE_STATE_COMPLETE, //! Indicates execution has completed.
192  EXECUTE_STATE_CANCEL, //! Indicates execution has been canceled. (Currently no different from <tt>COMPLETE</tt>.)
193  EXECUTE_STATE_SUSPEND, //! Indicates execution was suspended.
194  EXECUTE_STATE_WAIT, //! Indicates execution is not complete, but will resume after a set period of time.
195  EXECUTE_STATE_WAIT_NEXT, //! Indicates execution is not complete. Resume execution with the next call to <tt>Scheduler::Dispatch</tt>. Jobs in this state cannot be used in the background.
196  EXECUTE_STATE_CONTINUE_MAIN, //! Indicates execution is not complete. Next, execute in the main thread using the <tt>Dispatch</tt> function.
197  EXECUTE_STATE_CONTINUE_BACKGROUND, //! Indicates execution is not complete. The job will run in the background next.
198  EXECUTE_STATE_MAX //! Provided as a sentinel to indicate the last <tt>ExecuteState</tt> enumerated type.
199  };
200 
201 
202 /*!
203 @brief Represents the result of calling the <tt>Execute</tt> function.
204 */
206  {
207  public:
208 /*!
209 @brief Instantiates the object.
210 
211 @details If you specify a state other than <tt>EXECUTE_STATE_WAIT</tt>, call this overload, and only specify the <tt>ExecuteState</tt> value.
212 You can pass a value of type <tt>ExecuteState</tt> in the return value of the <tt>ExecuteCore</tt> function directly, because type conversion is performed implicitly.
213 */
215  : m_ExecuteState(executeState), m_WaitTime(0)
216  {
217  PIA_ASSERT(executeState >= 0 && executeState < EXECUTE_STATE_MAX);
218  }
219 
220 /*!
221 @brief Instantiates the object.
222 
223 @details If you specify <tt>EXECUTE_STATE_WAIT</tt>, use this overload to specify the state in addition to the wait time.
224 */
225  ExecuteResult(ExecuteState executeState, u16 waitTime)
226  : m_ExecuteState(executeState), m_WaitTime(waitTime)
227  {
228  PIA_ASSERT(executeState == EXECUTE_STATE_WAIT || waitTime == 0);
229  }
230 
231  u8 m_ExecuteState;
232  u8 m_Reserved;
233  u16 m_WaitTime;
234  };
235 
236 
237 protected:
238 /*!
239 @brief This pure virtual function is used to code the processing that the job executes.
240 
241 @details Use an override of this function to code the actual work done by the job.
242 */
243  virtual ExecuteResult ExecuteCore() = 0;
244 
245 
246 private:
247  enum InnerState
248  {
249  INNER_STATE_INITIAL,
250  INNER_STATE_FG_WAITING,
251  INNER_STATE_FG_READY,
252  INNER_STATE_FG_RUNNING,
253  INNER_STATE_BG_WAITING,
254  INNER_STATE_BG_READY,
255  INNER_STATE_BG_RUNNING,
256  INNER_STATE_SUSPEND,
257  INNER_STATE_COMPLETE,
258  INNER_STATE_NUM
259  };
260 
261 
262 /*!
263 @brief Gets a string representation of the job state.
264 
265 @return Returns a pointer to a string representation of the job state.
266 */
267  static const char* GetInnerStateString(InnerState innerState);
268 
269 
270  // Specifies the job's state.
271  volatile InnerState m_InnerState;
272 
273  // Indicates how many times the <tt>Execute</tt> function has been executed.
274  u32 m_ExecutedCount;
275 
276  // Indicates how much time is left until a job in waiting status can be switched to ready status.
277  Time m_ExecutionTime;
278 
279  // Represents a list node.
280  ListNode m_ListNode;
281 };
282 //! @endcond
283 }
284 }
285 } // end of namespace nn::pia::common
Indicates execution has completed.
Definition: common_Job.h:192
Indicates execution is not complete. The job will run in the background next.
Definition: common_Job.h:198
Indicates execution is not complete, but will resume after a set period of time.
Definition: common_Job.h:195
ExecuteResult(ExecuteState executeState)
Instantiates the object.
Definition: common_Job.h:214
ExecuteState
Indicates the type of execution result.
Definition: common_Job.h:188
Class that represents time.
Definition: common_Time.h:39
Definition: assert.h:115
Represents the result of calling the Execute function.
Definition: common_Job.h:205
ExecuteResult(ExecuteState executeState, u16 waitTime)
Instantiates the object.
Definition: common_Job.h:225
Indicates execution was suspended.
Definition: common_Job.h:194
Indicates execution is not complete. Resume execution with the next call to Scheduler::Dispatch. Jobs in this state cannot be used in the background.
Definition: common_Job.h:196
Indicates execution is not complete. Continue execution.
Definition: common_Job.h:191
Indicates execution is not complete. Next, execute in the main thread using the Dispatch function...
Definition: common_Job.h:197
Indicates execution has been canceled. (Currently no different from COMPLETE.)
Definition: common_Job.h:193