CTR Pia  4.11.3
Game Communication Engine
common_CachedPrint.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_CachedPrint.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_CriticalSection.h>
19 
20 
21 // @addtogroup pia_common_debug_macro Definitions of Debugging Macros Provided by the Pia Library
22 // @brief Specifies the debugging macros provided by the Pia library.
23 //! @{
24 //! @name Log Output
25 //! @{
26 
27 /*!
28 @def PIA_CACHED_PRINTF
29 @brief Caches console output. When no instance of <tt>CachedPrint</tt> has been generated, console output operates normally.
30 @param[in] ... Indicates that arguments are the same as <tt>printf</tt> in the standard library.
31 
32 */
33 #if NN_PIA_UNDER_DEVELOP
34 #define PIA_CACHED_PRINTF(...) \
35  if (::nn::pia::common::CachedPrint::GetInstance() != NULL) \
36  { \
37  ::nn::pia::common::CachedPrint::GetInstance()->Printf(__VA_ARGS__); \
38  } \
39  else \
40  { \
41  PIA_BASIC_REPORT(__VA_ARGS__); \
42  }
43 #else
44 #define PIA_CACHED_PRINTF(...) \
45  { \
46  }
47 #endif
48 
49 
50 /*!
51 @def PIA_CACHED_VPRINTF
52 @brief Caches console output. When no instance of <tt>CachedPrint</tt> has been generated, console output operates normally.
53 @param[in] format Specifies the output format string.
54 @param[in] varg A variable argument list.
55 
56 */
57 #if NN_PIA_UNDER_DEVELOP
58 #define PIA_CACHED_VPRINTF(format, varg) \
59  if (::nn::pia::common::CachedPrint::GetInstance() != NULL) \
60  { \
61  ::nn::pia::common::CachedPrint::GetInstance()->VPrintf((format), (varg)); \
62  } \
63  else \
64  { \
65  PIA_BASIC_VREPORT((format), (varg)); \
66  }
67 #else
68 #define PIA_CACHED_VPRINTF(format, varg) \
69  { \
70  (void)(format); \
71  (void)(varg); \
72  }
73 #endif
74 
75 //! @}
76 //! @}
77 
78 
79 namespace nn
80 {
81 namespace pia
82 {
83 namespace common
84 {
85 
86 /*!
87 @brief Caches console output.
88 This class is used for debugging. Do not use it in production versions of code.
89 @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.
90 @date 2012-05-01 Initial version.
91 
92 */
94 {
95 public:
96 /*!
97 @brief Creates an instance (singleton pattern).
98 @details Call this member function after calling <tt>nn::pia::common::BeginSetup</tt>, but before calling <tt>nn::pia::common::EndSetup</tt>.
99 
100 @param[in] bufferSize Specifies the size of the buffer to be cached (in bytes). Specify a value equal to or greater than <tt>512</tt>.
101 @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.
102 @retval ResultAlreadyExists Indicates that an instance has already been created. Programming error. Fix your program so that this error is not returned.
103 @retval ResultNotInitialized The <tt>common</tt> module has not been initialized. Programming error. Fix your program so that this error is not returned.
104 @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.
105 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
106 
107 
108 
109 
110 */
111  static nn::Result CreateInstance(u32 bufferSize);
112 
113 
114 /*!
115 @brief Destroys the instance (singleton pattern).
116 @details This function does nothing and returns if called when an instance has not been created.
117 
118 
119 */
120  static void DestroyInstance();
121 
122 
123 /*!
124 @brief Gets a pointer to the <tt>CachedPrint</tt> instance (singleton pattern).
125 @return Returns a <tt>NULL</tt> pointer if the instance cannot be created.
126 
127 */
129  {
130  return s_pInstance;
131  }
132 
133 
134 /*!
135 @brief Prints information useful for debugging.
136 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
137 
138 */
139  void Trace(u64 flag) const;
140 
141 
142 /*!
143 @cond PRIVATE
144 @brief Writes text strings to the cache.
145 @param[in] cpFormat Specifies the format string.
146 @param[in] varg Specifies the argument list.
147 
148 */
149  void VPrintf(const char* cpFormat, va_list varg);
150  //! @endcond
151 
152 
153 /*!
154 @cond PRIVATE
155 @brief Writes text strings to the cache.
156 @param[in] cpFormat Specifies the format string.
157 @param[in] Specifies variable length arguments.
158 
159 */
160  void Printf(const char* cpFormat, ...);
161  //! @endcond
162 
163 
164 /*!
165 @brief Clears the string currently being cached.
166 */
167  void Clear();
168 
169 
170 /*!
171 @brief Outputs the string currently being cached and then clears it.
172 */
173  void Flush();
174 
175 
176 /*!
177 @cond PRIVATE
178 @brief Gets the string currently being cached. Strings are null-terminated. (This function has not been verified. Do not use it yet.)
179 @param[out] pBuffer Specifies the buffer used to get the string.
180 @param[out] pLength The length of the string to get.
181 @param[in] bufferSize Specifies the buffer size (in bytes).
182 @return On success, returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function will return <tt>true</tt>.
183 @retval ResultInvalidArgument Indicates an invalid argument. Programming error. Fix your program so that this error is not returned.
184 @retval ResultNoData Indicates no string is currently being cached. A <tt>NULL</tt> terminator is still written to the specified buffer. Handle appropriately in the application.
185 
186 
187 
188 */
189  nn::Result Read(char* pBuffer, size_t* pLength, size_t bufferSize);
190  //! @endcond
191 
192 
193 private:
194  // Not implemented.
195  CachedPrint();
196  CachedPrint(const CachedPrint& rhs);
197  bool operator==(const CachedPrint& rhs) const;
198  bool operator!=(const CachedPrint& rhs) const;
199  CachedPrint& operator=(const CachedPrint& rhs);
200 
201  explicit CachedPrint(u32 bufferSize);
202  ~CachedPrint();
203 
204  static CachedPrint* s_pInstance;
205 
206  char* m_pBuffer;
207  u32 m_Size;
208 
209  u32 m_Top;
210  u32 m_Next;
211  u32 m_Repeat;
212 
213  CriticalSection m_CriticalSection;
214 };
215 }
216 }
217 } // end of namespace nn::pia::common
static CachedPrint * GetInstance()
Gets a pointer to the CachedPrint instance (singleton pattern).
Definition: common_CachedPrint.h:128
static void DestroyInstance()
Destroys the instance (singleton pattern).
void Clear()
Clears the string currently being cached.
void Flush()
Outputs the string currently being cached and then clears it.
void Trace(u64 flag) const
Prints information useful for debugging.
Definition: assert.h:115
Caches console output. This class is used for debugging. Do not use it in production versions of code...
Definition: common_CachedPrint.h:93
static nn::Result CreateInstance(u32 bufferSize)
Creates an instance (singleton pattern).
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40