CTR Pia  4.11.3
Game Communication Engine
transport_ThreadStreamManager.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: transport_ThreadStreamManager.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/transport/transport_definitions.h>
18 
19 // Forward declarations (common).
20 namespace nn
21 {
22 namespace pia
23 {
24 namespace common
25 {
26 class IPacketInput;
27 class IPacketOutput;
28 }
29 }
30 }
31 
32 
33 namespace nn
34 {
35 namespace pia
36 {
37 namespace transport
38 {
39 
40 // Forward declaration.
41 class TransportThreadStreamOld;
42 class NetworkFactory;
43 class SendThreadStream;
44 class ReceiveThreadStream;
45 
46 /*!
47 @brief Provides a unified interface for managing sending and receiving threads.
48 @details This class manages sending and receiving threads, including their creation and destruction.
49 It also provides functions for setting priority levels for sending or receiving threads and sleep intervals, and functions that have latency emulation features.
50 An instance of this class is created when the <tt>Transport</tt> class is initialized.
51 @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.
52 @date 2014-04-02 Changed the specifications of the <tt>SetSendThreadPacketLossRatio</tt> and <tt>SetReceiveThreadPacketLossRatio</tt> functions.
53 <tt>ResultInvalidState</tt> is returned when the packet loss emulation feature is not enabled.
54 @date 2014-04-02 Changed the specifications of the <tt>CreateInstance</tt> function. You can now specify whether to enable or disable packet loss emulation.
55 @date 2014-04-02 Revised the reference. The reference now refers to <tt>Transport::DebugSetting</tt> for details about the buffer size for latency emulation.
56 @date 2013-10-18 Fixed errors in the descriptions of <tt>GetSendThreadSendDataSize</tt> and <tt>ClearSendThreadSendDataSize</tt>.
57 @date 2013-10-18 Fixed errors in the descriptions of <tt>GetSendThreadSendPacketNum</tt> and <tt>ClearSendThreadSendPacketNum</tt>.
58 @date 2013-10-15 Added a feature to analyze and tabulate the data in sent and received packets.
59 @date 2013-09-02 Added functions to get and clear the send and receive data size.
60 @date 2012-08-24 Added a function for packet-loss emulation.
61 @date 2012-08-08 Added functions to get and clear the number of send and receive packets.
62 @date 2012-07-11 Added a description of how to set the priority for sending and receiving threads.
63 @date 2012-07-05 Added the <tt>SetSendThreadLatencyEmulation</tt> and <tt>SetReceiveThreadLatencyEmulation</tt> functions.
64 @date 2012-06-28 Clearly indicated which functions are thread-safe.
65 @date 2012-05-24 Initial version.
66 
67 
68 
69 */
71 {
72 public:
73 #if NN_PIA_CTR
74  static const s32 SEND_THREAD_DEFAULT_PRIORITY = 10; //!< Specifies the default priority for sending threads.
75  static const s32 RECEIVE_THREAD_DEFAULT_PRIORITY = 10; //!< Specifies the default priority for receiving threads.
76 #elif NN_PIA_WIN || NN_PIA_NIN_WIN
77  static const s32 SEND_THREAD_DEFAULT_PRIORITY = THREAD_PRIORITY_ABOVE_NORMAL; //!< Specifies the default priority for sending threads.
78  static const s32 RECEIVE_THREAD_DEFAULT_PRIORITY = THREAD_PRIORITY_ABOVE_NORMAL; //!< Specifies the default priority for receiving threads.
79 #elif NN_PIA_CAFE
80  static const s32 SEND_THREAD_DEFAULT_PRIORITY = 10; //!< Specifies the default priority for sending threads.
81  static const s32 RECEIVE_THREAD_DEFAULT_PRIORITY = 10; //!< Specifies the default priority for receiving threads.
82 #else
83 #error "Invalid platform"
84 #endif
85 
86  static const s32 SEND_THREAD_DEFAULT_SLEEP_SPAN = 5; //!< Specifies the default sleep duration (span) of sending threads. The value is in milliseconds.
87  static const s32 RECEIVE_THREAD_DEFAULT_SLEEP_SPAN = 5; //!< Specifies the default sleep duration (span) of receiving threads. The value is in milliseconds.
88 
89 /*!
90 @cond PRIVATE
91 @brief Creates an instance of the <tt>ThreadStreamManager</tt> class (singleton pattern).
92 @details This function is called from within the Pia library. Applications are not required to call this function directly.
93 @param[in] pFactory Specifies a pointer to a concrete class that inherits the <tt>NetworkFactory</tt> class.
94 @param[in] sendThreadMaxPacketNum Specifies the number of buffers in the send thread.
95 @param[in] receiveThreadMaxPacketNum Specifies the number of buffers in the receive thread.
96 @param[in] sendThreadLatencyEmulationPacketNum Specifies the number of buffers for emulating sending latency. (Set to zero to disable this feature.)
97 @param[in] receiveThreadLatencyEmulationPacketNum Specifies the number of buffers for emulating reception latency. (Set to zero to disable this feature.)
98 @param[in] bPacketLossEmulation Specifies whether packet loss emulation is enabled.
99 @return Returns a <tt>Result</tt> value that indicates success if the instance is created successfully.
100 @retval ResultInvalidArgument Indicates that an argument is invalid. (For example, a <tt>NULL</tt> pointer was specified.) Programming error. Fix your program so that this error is not returned.
101 @retval ResultNotInitialized Indicates that the <tt>transport</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
102 @retval ResultInvalidState Indicates that the instance was created at the wrong time. Programming error. Fix your program so that this error is not returned.
103 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
104 
105 
106 
107 
108 */
109  static nn::Result CreateInstance(NetworkFactory* pFactory,
110  size_t sendThreadMaxPacketNum,
111  size_t receiveThreadMaxPacketNum,
112  size_t sendThreadLatencyEmulationPacketNum,
113  size_t receiveThreadLatencyEmulationPacketNum,
114  bool bPacketLossEmulation);
115  //! @endcond
116 
117 
118 /*!
119 @cond PRIVATE
120 @brief Destroys the <tt>ThreadStreamManager</tt> class instance (singleton pattern).
121 @details This function is called from within the Pia library. Applications are not required to call this function directly.
122 
123 
124 */
125  static void DestroyInstance(void);
126  //! @endcond
127 
128 
129 /*!
130 @brief Gets the <tt>ThreadStreamManager</tt> class instance (singleton pattern).
131 @details This function returns a NULL pointer if an instance has not already been created.
132 @return Returns a pointer to the <tt>ThreadStreamManager</tt> instance.
133 
134 
135 */
137  {
138  return s_pInstance;
139  }
140 
141 
142 /*!
143 @cond PRIVATE
144 @brief Starts the send and receive threads.
145 @details This function is called from within the Pia library. Applications are not required to call this function directly.
146 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
147 @see Cleanup
148 
149 
150 */
151  nn::Result Startup(void);
152  //! @endcond
153 
154 
155 /*!
156 @cond PRIVATE
157 @brief Cleans up the send and receive threads.
158 @details This function is called from within the Pia library. Applications are not required to call this function directly.
159 @see Startup
160 
161 
162 */
163  void Cleanup(void);
164  //! @endcond
165 
166 
167 /*!
168 @cond PRIVATE
169 @brief Destroys the object.
170 */
171  ~ThreadStreamManager(void);
172  //! @endcond
173 
174 
175 /*!
176 @brief Sets the priority of the send thread.
177 @details In normal use, set the priority of the sending thread higher than that of the thread in which the application calls the <tt>common::Scheduler::Dispatch</tt> function.
178 @param[in] prio Specifies the priority of the send thread. We recommend adjusting these values to suit your application's specifications.
179 @see GetSendThreadPriority, common::Scheduler::Dispatch
180 
181 
182 
183 */
184  void SetSendThreadPriority(s32 prio);
185 
186 
187 /*!
188 @brief Gets the priority of the send thread.
189 @details This function is thread-safe.
190 
191 @return Returns the priority of the send thread.
192 @see SetSendThreadPriority
193 
194 */
195  s32 GetSendThreadPriority(void) const;
196 
197 
198 /*!
199 @brief Sets the priority of the receive thread.
200 @details In normal use, set the priority of the receiving thread higher than that of the thread in which the application calls the <tt>common::Scheduler::Dispatch</tt> function.
201 @param[in] prio Specifies the priority of the receive thread. We recommend adjusting these values to suit your application's specifications.
202 @see GetReceiveThreadPriority, common::Scheduler::Dispatch
203 
204 
205 
206 */
207  void SetReceiveThreadPriority(s32 prio);
208 
209 
210 /*!
211 @brief Gets the priority of the receive thread.
212 @details This function is thread-safe.
213 
214 @return Returns the priority of the receive thread.
215 @see SetReceiveThreadPriority
216 
217 */
218  s32 GetReceiveThreadPriority(void) const;
219 
220 
221 /*!
222 @brief Sets the sleep interval of the send thread.
223 @details The send thread sleeps periodically. This function sets the sleep interval.
224 
225 @param[in] span Specifies the periodic interval at which to make the send thread sleep. The value is in milliseconds. We recommend adjusting these values to suit your application's specifications.
226 @see GetSendThreadSleepTimeSpan
227 
228 */
229  void SetSendThreadSleepTimeSpan(u32 span);
230 
231 
232 /*!
233 @brief Gets the sleep interval of the send thread.
234 @details This function is thread-safe.
235 
236 @return Returns the sleep interval of the send thread. The value is in milliseconds.
237 @see SetSendThreadSleepTimeSpan
238 
239 */
240  u32 GetSendThreadSleepTimeSpan(void) const;
241 
242 
243 /*!
244 @brief Sets the sleep interval of the receive thread.
245 @details The receive thread sleeps periodically. This function sets the sleep interval.
246 
247 @param[in] span Specifies the sleep interval for the receive thread. The value is in milliseconds. We recommend adjusting these values to suit your application's specifications.
248 @see GetReceiveThreadSleepTimeSpan
249 
250 */
251  void SetReceiveThreadSleepTimeSpan(u32 span);
252 
253 
254 /*!
255 @brief Gets the sleep interval of the receive thread.
256 @details This function is thread-safe.
257 
258 @return Returns the sleep interval of the receive thread. The value is in milliseconds.
259 @see SetReceiveThreadSleepTimeSpan
260 
261 */
262  u32 GetReceiveThreadSleepTimeSpan(void) const;
263 
264 
265 /*!
266 @brief Sets the send latency time to emulate.
267 @details The sending latency emulation feature does not immediately send the packets that are created, but instead temporarily saves them to a buffer. After the prescribed amount of time passes, it then sends the saved packets.
268 For this reason, if you increase the maximum delay time without preparing a buffer of an appropriate size, the buffer overflows and packets appear to be lost frequently.
269 For more information about setting the buffer size, see the <tt>Transport::DebugSetting</tt> structure.
270 @param[in] minLatency Specifies the minimum latency. The value is in milliseconds.
271 @param[in] maxLatency Specifies the maximum latency. The value is in milliseconds.
272 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
273 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
274 @retval ResultInvalidState Indicates that the latency emulation feature may be disabled. Programming error. Fix your program so that this error is not returned.
275 @see SetReceiveThreadLatencyEmulation, Transport::DebugSetting
276 
277 
278 
279 
280 
281 
282 */
283  nn::Result SetSendThreadLatencyEmulation(s32 minLatency, s32 maxLatency);
284 
285 
286 /*!
287 @brief Sets the receive latency time to emulate.
288 @details The receiving latency emulation feature does not immediately pass the received packets to higher layers, but instead temporarily saves them to a buffer. After the prescribed amount of time passes, it then passes the saved packets to the higher layers.
289 For this reason, if you increase the maximum delay time without preparing a buffer of an appropriate size, the buffer overflows and packets appear to be lost frequently.
290 For more information about setting the buffer size, see the <tt>Transport::DebugSetting</tt> structure.
291 @param[in] minLatency Specifies the minimum latency. The value is in milliseconds.
292 @param[in] maxLatency Specifies the maximum latency. The value is in milliseconds.
293 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
294 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
295 @retval ResultInvalidState Indicates that the latency emulation feature may be disabled. Programming error. Fix your program so that this error is not returned.
296 @see SetSendThreadLatencyEmulation, Transport::DebugSetting
297 
298 
299 
300 
301 
302 
303 */
304  nn::Result SetReceiveThreadLatencyEmulation(s32 minLatency, s32 maxLatency);
305 
306 
307 /*!
308 @brief Gets the number of times the send thread attempted to send packets.
309 @details The send thread maintains a count of the packets that it attempted to send.
310 This function returns that count.
311 @return Returns the total number of packets that the thread attempted to send.
312 @see ClearSendThreadSendPacketNum
313 
314 
315 */
316  size_t GetSendThreadSendPacketNum(void) const;
317 
318 
319 /*!
320 @brief Clears the sent packet count.
321 @details This function clears the counter representing the number of packets that the thread attempted to send. You can use the <tt>GetSendThreadSendPacketNum</tt> function to get the value of this counter.
322 @see GetSendThreadSendPacketNum
323 
324 
325 
326 */
327  void ClearSendThreadSendPacketNum(void);
328 
329 
330 /*!
331 @brief Gets the number of times the receive thread has successfully received packets.
332 @details The receive thread maintains a count of the packets that it successfully receives.
333 This function returns that count.
334 @return Returns the total number of packets that have been received successfully.
335 @see ClearReceiveThreadReceivePacketNum
336 
337 
338 */
339  size_t GetReceiveThreadReceivePacketNum(void) const;
340 
341 
342 /*!
343 @brief Clears the received packet count.
344 @details This functions clears the counter representing the number of packets successfully received. You can use the <tt>GetReceiveThreadReceivePacketNum</tt> function to get the value of this counter.
345 @see GetReceiveThreadReceivePacketNum
346 
347 
348 
349 */
350  void ClearReceiveThreadReceivePacketNum(void);
351 
352 
353 /*!
354 @brief Gets the total amount of data that the send thread attempted to send.
355 @details The send thread maintains a count of the amount of data it attempted to send.
356 This function returns that count.
357 @return Returns the total amount of data that the thread attempted to send. The value is in bytes.
358 @see ClearSendThreadSendDataSize
359 
360 
361 */
362  u64 GetSendThreadSendDataSize(void) const;
363 
364 
365 /*!
366 @brief Clears the counter tracking the amount of data sent.
367 @details This function clears the counter representing the amount of data that the thread attempted to send. You can use the <tt>GetSendThreadSendDataSize</tt> function to get the value of this counter.
368 @see GetSendThreadSendDataSize
369 
370 
371 
372 */
373  void ClearSendThreadSendDataSize(void);
374 
375 
376 /*!
377 @brief Gets the total amount of data successfully received in the receive thread.
378 @details The receive thread maintains a count of the amount of data it successfully receives.
379 This function returns that count.
380 @return Returns the total amount of data that has been received successfully. The value is in bytes.
381 @see ClearReceiveThreadReceiveDataSize
382 
383 
384 */
385  u64 GetReceiveThreadReceiveDataSize(void) const;
386 
387 
388 /*!
389 @brief Clears the counter tracking the amount of data received.
390 @details This functions clears the counter representing the amount of data successfully received. You can use the <tt>GetReceiveThreadSendDataSize</tt> function to get the value of this counter.
391 @see GetReceiveThreadReceiveDataSize
392 
393 
394 
395 */
396  void ClearReceiveThreadReceiveDataSize(void);
397 
398 
399 /*!
400 @brief Sets the packet loss rate to emulate on the send thread.
401 @details You can use this packet loss emulation feature to emulate cases in which packets were sent successfully, but were later lost for some reason.
402 Setting a value other than <tt>0%</tt> in the argument emulates that rate of packet loss by having the sending thread drop the specified percentage of packets.
403 By default, the packet loss rate on the send thread is set to 0%.
404 @param[in] lossPercentage Specifies a value in the range from 0 through 100.
405 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
406 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
407 @retval ResultInvalidState The packet loss emulation feature is not set to enabled. Programming error. Fix your program so that this error is not returned.
408 @see GetSendThreadPacketLossRatio, Transport::SetDebugSetting
409 
410 
411 
412 
413 
414 */
415  nn::Result SetSendThreadPacketLossRatio(s32 lossPercentage);
416 
417 
418 /*!
419 @brief Gets the packet loss rate emulated on the send thread.
420 @return Returns the packet loss rate set for the send thread. The value is in the range from 0 through 100.
421 @see SetSendThreadPacketLossRatio
422 
423 */
424  s32 GetSendThreadPacketLossRatio(void) const;
425 
426 
427 /*!
428 @brief Sets the packet loss rate to emulate on the receive thread.
429 @details You can use this packet loss emulation feature to emulate cases in which incoming packets were lost for some reason.
430 Setting a value other than <tt>0%</tt> in the argument will emulate that rate of packet loss by having the receiving thread drop the specified percentage of packets.
431 By default, the packet loss rate on the receive thread is set to 0%.
432 @param[in] lossPercentage Specifies a value in the range from 0 through 100.
433 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
434 @retval ResultInvalidArgument Specifies that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
435 @retval ResultInvalidState The packet loss emulation feature is not set to enabled. Programming error. Fix your program so that this error is not returned.
436 @see GetReceiveThreadPacketLossRatio, Transport::SetDebugSetting
437 
438 
439 
440 
441 */
442  nn::Result SetReceiveThreadPacketLossRatio(s32 lossPercentage);
443 
444 
445 /*!
446 @brief Gets the packet loss rate to emulate on the receive thread.
447 @return Returns the packet loss rate set for the receive thread. The value is in the range from 0 through 100.
448 @see SetReceiveThreadPacketLossRatio
449 
450 */
451  s32 GetReceiveThreadPacketLossRatio(void) const;
452 
453 
454 /*!
455 @cond PRIVATE
456 @brief Gets a pointer to a <tt>ReceiveThreadStreamOld</tt> instance (non-<tt>const</tt> version).
457 */
458  ReceiveThreadStream* GetReceiveStream(void)
459  {
460  return m_pReceiveStream;
461  }
462  //! @endcond
463 
464 
465 /*!
466 @cond PRIVATE
467 @brief Gets a pointer to a <tt>ReceiveThreadStreamOld</tt> instance (<tt>const</tt> version).
468 */
469  const ReceiveThreadStream* GetReceiveStream(void) const
470  {
471  return m_pReceiveStream;
472  }
473  //! @endcond
474 
475 
476 /*!
477 @cond PRIVATE
478 @brief Gets a pointer to a <tt>SendThreadStreamOld</tt> instance (non-<tt>const</tt> version).
479 */
480  SendThreadStream* GetSendStream(void)
481  {
482  return m_pSendStream;
483  }
484  //! @endcond
485 
486 
487 /*!
488 @cond PRIVATE
489 @brief Gets a pointer to a <tt>SendThreadStreamOld</tt> instance (<tt>const</tt> version).
490 */
491  const SendThreadStream* GetSendStream(void) const
492  {
493  return m_pSendStream;
494  }
495  //! @endcond
496 
497 
498 /*!
499 @cond PRIVATE
500 @brief Provided for <tt>NexFacade</tt>.
501 */
502  common::IPacketInput* GetInputStream(void)
503  {
504  return m_pInputStream;
505  }
506  //! @endcond
507 
508 /*!
509 @cond PRIVATE
510 @brief Provided for <tt>NexFacade</tt>.
511 */
512  common::IPacketOutput* GetOutputStream(void)
513  {
514  return m_pOutputStream;
515  }
516  //! @endcond
517 
518 
519 /*!
520 @cond PRIVATE
521 @brief Sets monitoring data.
522 */
523  void SetMonitoringData(void);
524  //! @endcond
525 
526 
527 /*!
528 @brief Prints information that is useful for debugging.
529 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
530 
531 */
532  virtual void Trace(u64 flag) const;
533 
534 
535 #if NN_PIA_ENABLE_STATISTIC_THREAD_STREAM_BLOCK_TIME
536  void ResetThreadStreamStatistic();
537  void PrintThreadStreamStatistic(u32 printMaxDataNum);
538 #endif
539 
540 private:
541 /*!
542 @brief No default constructor is used. A factory pointer is assumed.
543 */
544  ThreadStreamManager(void);
545 
546 /*!
547 @brief Instantiates the object with the specified arguments.
548 */
550  size_t sendThreadMaxPacketNum,
551  size_t receiveThreadMaxPacketNum,
552  size_t sendThreadLatencyEmulationPacketNum,
553  size_t receiveThreadLatencyEmulationPacketNum,
554  bool bPacketLossEmulation);
555 
556 /*!
557 @brief This copy constructor is private because the singleton pattern is used.
558 */
560 
561 /*!
562 @brief This assignment operator is private because the singleton pattern is used.
563 */
564  ThreadStreamManager& operator=(const ThreadStreamManager&);
565 
566 
567  // Specify variables that receive the pointers created by the factory.
568  common::IPacketInput* m_pInputStream;
569  common::IPacketOutput* m_pOutputStream;
570 
571  ReceiveThreadStream* m_pReceiveStream;
572  SendThreadStream* m_pSendStream;
573 
574  static ThreadStreamManager* s_pInstance;
575 };
576 }
577 }
578 } // end of namespace nn::pia::transport
static ThreadStreamManager * GetInstance(void)
Gets the ThreadStreamManager class instance (singleton pattern).
Definition: transport_ThreadStreamManager.h:136
Definition: assert.h:115
Provides a unified interface for managing sending and receiving threads.
Definition: transport_ThreadStreamManager.h:70
An interface (factory pattern) for generating the classes needed by the network.
Definition: transport_NetworkFactory.h:89
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40