CTR-Pia  5.4.3
Game Communication Engine
 全て クラス ネームスペース 関数 変数 型定義 列挙型 列挙型の値 ページ
common_Job.h
1 /*--------------------------------------------------------------------------------*
2  Copyright (C)Nintendo All rights reserved.
3 
4  These coded instructions, statements, and computer programs contain proprietary
5  information of Nintendo and/or its licensed developers and are protected by
6  national and international copyright laws. They may not be disclosed to third
7  parties or copied or duplicated in any form, in whole or in part, without the
8  prior written consent of Nintendo.
9 
10  The content herein is highly confidential and should be handled accordingly.
11  *--------------------------------------------------------------------------------*/
12 
13 
14 #pragma once
15 
16 #include <nn/pia/common/common_Definitions.h>
17 #include <nn/pia/common/common_ListNode.h>
18 #include <nn/pia/common/common_Time.h>
19 
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace common
25 {
26 
27 /*!
28  @cond PRIVATE
29  @brief ジョブの基底クラスです。
30 
31  @details ジョブの機能を利用するには、派生クラスで
32  純粋仮想関数のExecuteCore()をオーバーライドする必要があります。
33  */
34 class Job : public RootObject
35 {
36 public:
37  /*!
38  @brief ジョブの状態を表現する列挙型です。
39  */
40  enum State
41  {
42  State_Initial, //! ジョブのインスタンスを作成した直後の状態です。
43  State_Waiting, //! ジョブは待ち状態にあります。指定された時間が経過するまで、ジョブは実行されません。
44  State_Suspend, //! ジョブは一時停止状態にあります。
45  State_Ready, //! ジョブは実行可能状態にあります。
46  State_Running, //! ジョブが実行中であることを示す状態です。
47  State_Complete, //! ジョブの処理が完了したことを示す状態です。
48  State_Max //! enum State型の末端を示すために用意したものです。
49  };
50 
51 
52  /*!
53  @brief コンストラクタです。
54 
55  @details 本クラスには純粋仮想関数が含まれているため、ジョブの機能を利用するには、
56  このクラスから派生させたクラスを作成する必要があります。
57  */
58  Job();
59 
60 
61  /*!
62  @brief デストラクタです。
63  */
64  virtual ~Job();
65 
66 
67  /*!
68  @brief ジョブをリセットして、再利用可能にします。
69 
70  @details スケジューラによって実行されたジョブを再び利用可能にする時などに呼び出します。
71  このメンバ関数呼び出しにより、インスタンスはコンストラクタ実行直後の状態と
72  等価になります。
73  状態が State_Running の時(ExecuteCore実行中)に呼ぶとアサートにかかります。
74  その他の状態の時に呼び出すと成功しますが、State_Initial, State_Complete
75  以外の時にこの関数を呼び出すと、警告メッセージが出力されることがあります。
76  */
77  virtual void Reset(bool isCheck = true);
78 
79 
80  /*!
81  @brief 初期化済み状態(State_Initial)のジョブを実行可能(State_Ready)にします。
82 
83  @details その他の状態の時に呼び出すと、アサートにかかります。
84  <br>
85  @param[in] isBackground BackgroundScheduler を使って別スレッドで処理を行う場合は true を指定します。
86  */
87  void Ready(bool isBackground = false);
88 
89 
90  /*!
91  @brief サスペンド状態(State_Suspend)のジョブを実行可能(State_Ready)にします。
92 
93  @details その他の状態の時に呼び出すと、アサートにかかります。
94  <br>
95  @param[in] isBackground BackgroundScheduler を使って別スレッドで処理を行う場合は true を指定します。
96  */
97  void Resume(bool isBackground = false);
98 
99 
100  /*!
101  @brief ジョブを中断します。
102 
103  @details 動作自体は Reset() と同じですが、警告メッセージを出しません。
104  */
105  void Cancel()
106  {
107  Reset(false);
108  }
109 
110 
111  /*!
112  @brief ジョブの状態を取得します。
113 
114  @return 現在のジョブの状態が返ります。
115  */
116  State GetState() const;
117 
118 
119  /*!
120  @brief ジョブを実行中か
121  @return State_Waiting, State_Ready, State_Running, State_Suspend のいずれかの状態ならtrueを返します。
122  */
123  bool IsRunning() const;
124 
125 
126  /*!
127  @brief フォアグラウンド実行中か
128  @return フォアグラウンドの State_Waiting, State_Ready, State_Running のいずれかの状態ならtrueを返します。
129  */
130  bool IsForeground() const;
131 
132  /*!
133  @brief バックグラウンド実行中か
134  @return バックグラウンドの State_Waiting, State_Ready, State_Running のいずれかの状態ならtrueを返します。
135  */
136  bool IsBackground() const;
137 
138 
139  /*!
140  @brief ジョブが何回実行されたかを得ます。
141 
142  @return まだ一度もExecute()が実行されていない状態では、ゼロが返されます。
143  カウンタのインクリメントは、ExecuteCore()の実行後に行われます。
144  */
145  uint32_t GetExecutedCount() const
146  {
147  return m_ExecutedCount;
148  }
149 
150 
151  /*!
152  @brief 待ち状態にあるジョブが次回に実行される時刻を得ます。
153 
154  @return 返り値の単位はTickです。
155  */
156  const Time& GetExecutionTime() const
157  {
158  return m_ExecutionTime;
159  }
160 
161 
162  /*!
163  @cond PRIVATE
164  @brief ジョブを実行します。
165 
166  @details このメンバ関数は、スケジューラによって呼び出されることを想定しています。
167  アプリケーションプログラムがこの関数を直接呼び出してはいけません。
168  */
169  void Execute(bool isBackground);
170  //! @endcond
171 
172 
173  /*!
174  @cond PRIVATE
175  @brief リストノードのオフセットです。
176  */
177  static int32_t GetListNodeOffset()
178  {
179  NN_PIA_PRAGMA_PUSH_WARNINGS
180  NN_PIA_DISABLE_WARNING_CLANG_INVALID_OFFSETOF
181  return offsetof(Job, m_ListNode);
182  NN_PIA_PRAGMA_POP_WARNINGS
183  }
184  //! @endcond
185 
186 
187  /*!
188  @brief Executeの結果の種類を表します。
189  */
190  enum ExecuteState
191  {
192  ExecuteState_Continue, //! 処理が完了していません。続けて実行します。
193  ExecuteState_Complete, //! 処理が完了しました。
194  ExecuteState_Cancel, //! 処理が中断されました。(現状COMPLETEと区別してない)
195  ExecuteState_Suspend, //! 処理は一時中断状態になりました。
196  ExecuteState_Wait, //! 処理は完了していないので一定時間後に再開します。
197  ExecuteState_WaitNext, //! 処理は完了していません。次の Scheduler::Dispatch() で再開します。バックグラウンドでは使えません。
198  ExecuteState_ContinueMain, //! 処理が完了していません。次はメインの Dispatch() で実行します。
199  ExecuteState_ContinueBackground, //! 処理が完了していません。次はバックグラウンドから実行します。
200  ExecuteState_Max //! enum ExecuteState型の末端を示すために用意したものです。
201  };
202  PIA_COMPILE_ASSERT(ExecuteState_Max < 255); // ExecuteState の enum を uint8_t の変数に格納している都合で、上限チェックのコードを入れておきます。
203 
204  /*!
205  @brief Executeの結果を表します。
206  */
207  struct ExecuteResult
208  {
209  public:
210  /*!
211  @brief コンストラクタ
212 
213  @details ExecuteState_Wait 以外を指定するときは、このオーバーロードを使ってExecuteStateだけ指定する必要があります。
214  暗黙の型変換を可能にしていますのでExecuteCoreの返り値にExecuteStateを直接渡すことができます。
215  */
216  ExecuteResult(ExecuteState executeState)
217  : m_ExecuteState(static_cast<uint8_t>(executeState)), m_WaitTime(0)
218  {
219  PIA_ASSERT(executeState >= 0 && executeState < ExecuteState_Max);
220  }
221 
222  /*!
223  @brief コンストラクタ
224 
225  @details ExecuteState_Wait を指定するときは、このオーバーロードを使って待ち時間を含めて設定する必要があります。
226  */
227  ExecuteResult(ExecuteState executeState, uint16_t waitTime)
228  : m_ExecuteState(static_cast<uint8_t>(executeState)), m_WaitTime(waitTime)
229  {
230  PIA_ASSERT(executeState == ExecuteState_Wait || waitTime == 0);
231  }
232 
233  uint8_t m_ExecuteState;
234  uint8_t m_Reserved;
235  uint16_t m_WaitTime;
236  };
237 
238 
239 protected:
240  /*!
241  @brief ジョブで実行される処理を記述するための純粋仮想関数です。
242 
243  @details 実際に実行する処理は、この関数をオーバーライドして記述します。
244  */
245  virtual ExecuteResult ExecuteCore() = 0;
246 
247 
248 private:
249  enum InnerState
250  {
251  InnerState_Initial,
252  InnerState_FgWaiting,
253  InnerState_FgReady,
254  InnerState_FgRunning,
255  InnerState_BgWaiting,
256  InnerState_BgReady,
257  InnerState_BgRunning,
258  InnerState_Suspend,
259  InnerState_Complete,
260  InnerState_Num
261  };
262 
263 
264  /*!
265  @brief ジョブの状態の文字列表現を得ます。
266 
267  @return ジョブの状態を表す文字列へのポインタが返されます。
268  */
269  static const char* GetInnerStateString(InnerState innerState);
270 
271 
272  // ジョブの状態を表すメンバ変数です。
273  volatile InnerState m_InnerState;
274 
275  // 何度Execute()が実行されたかを示すメンバ変数です。
276  uint32_t m_ExecutedCount;
277 
278  // 待ち状態にあるジョブが、実行可能状態に遷移できる時刻を保持します。
279  Time m_ExecutionTime;
280 
281  // リストノード。
282  ListNode m_ListNode;
283 };
284 //! @endcond
285 }
286 }
287 } // end of namespace nn::pia::common