CTR Pia  4.11.3
Game Communication Engine
common_Scheduler.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_Scheduler.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_OffsetList.h>
19 #include <pia/common/common_Time.h>
20 #include <pia/common/common_CriticalSection.h>
21 
22 
23 namespace nn
24 {
25 namespace pia
26 {
27 namespace common
28 {
29 
30 class Time;
31 class Job;
32 class BackgroundScheduler;
33 
34 /*!
35 @brief Represents a job scheduler.
36 @details The scheduler object is used to asynchronously execute processes defined by the <tt>Job</tt> class.
37 This class is not thread-safe.
38 @date 2014-09-18 Changed the specifications so that <tt>ResultAlreadyExists</tt> is returned if you call <tt>CreateInstance</tt> when an instance already exists.
39 @date 2012-07-03 Changed the background scheduler priority check.
40 @date 2012-06-15 The <tt>Dispatch</tt> function used to return <tt>nn::Result</tt>, but no longer returns a value.
41 @date 2012-05-21 Added a feature for running jobs in a different thread. The parameters and return values of <tt>CreateInstance</tt> have been changed accordingly.
42 @date 2012-04-04 Initial version.
43 
44 
45 
46 */
48 {
49 public:
50 /*!
51 @brief Specifies the default priority value threads used by the background scheduler.
52 */
53 #if NN_PIA_CTR
54  static const s32 DEFAULT_BACKGROUND_THREAD_PRIORITY = 24;
55 #elif NN_PIA_WIN || NN_PIA_NIN_WIN
56  static const s32 DEFAULT_BACKGROUND_THREAD_PRIORITY = THREAD_PRIORITY_BELOW_NORMAL;
57 #elif NN_PIA_CAFE
58  static const s32 DEFAULT_BACKGROUND_THREAD_PRIORITY = 24;
59 #else
60 #error "Invalid platform";
61 #endif
62 
63 
64 /*!
65 @brief Creates an instance (singleton pattern).
66 @details Call this member function after calling <tt>nn::pia::common::BeginSetup</tt>, but before calling <tt>nn::pia::common::EndSetup</tt>.
67 @param[in] backgroundThreadPriority Specifies the priority of the thread used by the background scheduler. Be sure to specify a priority lower than the thread used to call Pia member functions.
68 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully. You must make sure that the implementation of this function in your application does not return any errors.
69 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
70 @retval ResultNotInitialized The <tt>common</tt> module has not been initialized. Programming error. Fix your program so that this error is not returned.
71 @retval ResultInvalidState Indicates that the function was not called between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
72 @retval ResultInvalidArgument Indicates an argument is invalid. Programming error. Fix your program so that this error is not returned.
73 
74 
75 
76 
77 
78 */
79  static nn::Result CreateInstance(s32 backgroundThreadPriority = DEFAULT_BACKGROUND_THREAD_PRIORITY);
80 
81 
82 /*!
83 @brief Destroys the instance (singleton pattern).
84 @details If this function is called when an instance has not been created, it does nothing and returns.
85 
86 
87 */
88  static void DestroyInstance();
89 
90 
91 /*!
92 @brief Gets a pointer to the <tt>Scheduler</tt> instance (singleton pattern).
93 @return Returns a <tt>NULL</tt> pointer if the instance cannot be created.
94 
95 */
97  {
98  return s_pInstance;
99  }
100 
101 
102 /*!
103 @brief Dispatches jobs.
104 @details Jobs are run by calling this function.
105 
106 @param[in] timeout Specifies the timeout value serving as the upper limit for job execution. The value is in milliseconds.
107 There is, however, no guarantee that jobs will occur within the timeout period.
108 A value of zero is interpreted as if no timeout was specified.
109 
110 */
111  void Dispatch(u32 timeout = 0);
112 
113 
114 /*!
115 @cond PRIVATE
116 @brief Registers a job.
117 
118 @details Do not call this function from another thread as it is called by a job.
119 */
120  void EntryJob(Job* pJob, bool isBackground);
121  //! @endcond
122 
123 
124 /*!
125 @cond PRIVATE
126 @brief Registers a job that waits for the next call to <tt>Dispatch</tt>.
127 
128 @details Do not call this function from another thread as it is called by a job.
129 */
130  void EntryJobNext(Job* pJob);
131  //! @endcond
132 
133 
134 /*!
135 @cond PRIVATE
136 @brief Removes a job.
137 
138 @details Do not call this function from another thread as it is called by a job.
139 */
140  void ResetJob(Job* pJob);
141  //! @endcond
142 
143 
144 /*!
145 @cond PRIVATE
146 @brief Gets the time at which <tt>Dispatch</tt> was called.
147 */
148  const Time& GetDispatchedTime() const
149  {
150  return m_DispatchedTime;
151  }
152  //! @endcond
153 
154 
155 /*!
156 @cond PRIVATE
157 @brief Gets the job-related <tt>CriticalSection</tt>.
158 */
159  CriticalSection* GetCriticalSection()
160  {
161  return &m_CriticalSection;
162  }
163  //! @endcond
164 /*!
165 @cond PRIVATE
166 @brief Gets the number of jobs currently waiting.
167 */
168  u32 GetJobNum() const;
169  //! @endcond
170 
171 
172 /*!
173 @cond PRIVATE
174 @brief Sets monitoring data.
175 */
176  void SetMonitoringData();
177  //! @endcond
178 
179 
180 /*!
181 @brief Prints information that is useful for debugging.
182 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
183 
184 */
185  virtual void Trace(u64 flag) const;
186 
187 private:
188 /*!
189 @brief Instantiates the <tt>Scheduler</tt> object.
190 */
191  explicit Scheduler(s32 backgroundThreadPriority);
192 
193 /*!
194 @brief Destroys the <tt>Scheduler</tt>.
195 */
196  ~Scheduler();
197 
198 
199  Scheduler(const Scheduler&);
200  Scheduler& operator=(const Scheduler&);
201 
202  // A pointer to a singleton instance.
203  static Scheduler* s_pInstance;
204 
205 
206  //! The job list type.
207  typedef OffsetList<Job> JobList;
208 
209  //! Job lists.
210  JobList m_JobList;
211  JobList m_CountBasedJobList;
212 
213  //! Specifies the dispatch time.
214  Time m_DispatchedTime;
215 
216  //! The number of times <tt>Dispatch</tt> is called.
217  u32 m_DispatchCalls;
218 
219  mutable CriticalSection m_CriticalSection;
220 
221  BackgroundScheduler* m_pBackgroundScheduler;
222 };
223 }
224 }
225 } // end of namespace nn::pia::common
static nn::Result CreateInstance(s32 backgroundThreadPriority=DEFAULT_BACKGROUND_THREAD_PRIORITY)
Creates an instance (singleton pattern).
Represents a job scheduler.
Definition: common_Scheduler.h:47
static Scheduler * GetInstance()
Gets a pointer to the Scheduler instance (singleton pattern).
Definition: common_Scheduler.h:96
Class that represents time.
Definition: common_Time.h:39
Definition: assert.h:115
static const s32 DEFAULT_BACKGROUND_THREAD_PRIORITY
Specifies the default priority value threads used by the background scheduler.
Definition: common_Scheduler.h:54
void Dispatch(u32 timeout=0)
Dispatches jobs.
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
static void DestroyInstance()
Destroys the instance (singleton pattern).
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40