CTR Pia  4.11.3
Game Communication Engine
common_Watermark.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: common_Watermark.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 
19 #include <pia/common/common_RootObject.h>
20 
21 
22 namespace nn
23 {
24 namespace pia
25 {
26 namespace common
27 {
28 
29 
30 /*!
31 @brief Contains member functions for profiling things like peak values in the Pia library's resource usage (unsupported).
32 
33 @date 2012-04-04 Initial version.
34 */
35 class Watermark : public RootObject
36 {
37 public:
38 /*!
39 @brief Specifies the maximum length of a name that can be set using the <tt>SetName</tt> function.
40 
41 @see SetName
42 */
43  static const size_t MAX_NAME_LENGTH = 63;
44 
45 
46 /*!
47 @brief Instantiates the object with default parameters (default constructor).
48 The instance is constructed with <tt>Update</tt> functionality disabled.
49 */
50  Watermark(void);
51 
52 
53 /*!
54 @brief Destroys the object.
55 */
56  ~Watermark(void);
57 
58 
59 /*!
60 @brief Enables updating values with the <tt>Update</tt> function.
61 
62 @details If you call <tt>Update</tt> while updating is enabled, minimum and maximum values are updated as necessary, values that can be retrieved with <tt>GetLatestValue</tt> are updated, and the counter that tracks the number of calls to <tt>Update</tt> is incremented.
63 @see DisableUpdate, IsUpdateEnabled
64 
65 
66 */
67  void EnableUpdate(void)
68  {
69  m_Enabled = true;
70  }
71 
72 
73 /*!
74 @brief Disables updating values with <tt>Update</tt>.
75 
76 @details If updating is disabled, these values (the minimum, maximum, updated value, and number of calls to the <tt>Update</tt> function) are not updated even if you call <tt>Update</tt>.
77 
78 @see EnableUpdate, IsUpdateEnabled
79 */
80  void DisableUpdate(void)
81  {
82  m_Enabled = false;
83  }
84 
85 
86 /*!
87 @brief Returns whether <tt>Update</tt> functionality is enabled.
88 
89 @return Returns <tt>true</tt> if updating values with <tt>Update</tt> is enabled; returns <tt>false</tt> otherwise.
90 @see EnableUpdate, DisableUpdate
91 */
92  bool IsUpdateEnabled(void) const
93  {
94  return m_Enabled;
95  }
96 
97 
98 /*!
99 @brief Sets a name for the instance.
100 
101 @param[in] pName Specifies the name to set. The specified string must be <tt>NULL</tt>-terminated and no longer than <tt>MAX_NAME_LENGTH</tt>.
102 The function asserts if an invalid pointer is specified or the name is too long.
103 @see GetName
104 */
105  void SetName(const char* pName);
106 
107 
108 /*!
109 @brief Gets the name of an instance.
110 
111 @return Returns a pointer to the character array storing the name.
112 @see SetName
113 */
114  const char* GetName(void) const
115  {
116  return m_Name;
117  }
118 
119 
120 /*!
121 @brief Re-initializes the values maintained by the instance (maximum, minimum, updated values, and the number of calls to <tt>Update</tt>).
122 
123 @details Calling this function does not change the name set using <tt>SetName</tt> or change whether <tt>Update</tt> functionality is enabled or disabled.
124 @see SetName, EnableUpdate, DisableUpdate, IsUpdateEnabled
125 */
126  void Reset(void);
127 
128 
129 /*!
130 @brief Updates the value.
131 @details If you call this function while <tt>Update</tt> functionality is enabled, the values being used so far for the maximum, minimum, update value, and number of calls to <tt>Update</tt> are all updated appropriately.
132 If you call this function while <tt>Update</tt> functionality is disabled, it does nothing and returns.
133 
134 @param[in] value Specifies the value being monitored.
135 @see EnableUpdate, DisableUpdate, IsUpdateEnabled, GetMaxValue, GetMinValue, GetLatestValue, GetUpdateCount
136 
137 
138 
139 
140 */
141  void Update(s64 value);
142 
143 
144 /*!
145 @brief Gets the maximum value currently being used by <tt>Update</tt>.
146 
147 @see Update, GetMinValue, GetLatestValue, GetUpdateCount
148 */
149  s64 GetMaxValue(void) const
150  {
151  return m_MaxValue;
152  }
153 
154 
155 /*!
156 @brief Gets the minimum value currently being used by <tt>Update</tt>.
157 
158 @see Update, GetMaxValue, GetLatestValue, GetUpdateCount
159 */
160  s64 GetMinValue(void) const
161  {
162  return m_MinValue;
163  }
164 
165 
166 /*!
167 @brief Gets the update value passed in the last call to <tt>Update</tt>.
168 
169 @see Update, GetMinValue, GetMaxValue, GetUpdateCount
170 */
171  s64 GetLatestValue(void) const
172  {
173  return m_LatestValue;
174  }
175 
176 /*!
177 @brief Gets the number of times <tt>Update</tt> has been called so far.
178 
179 @see Update, GetMaxValue, GetMinValue, GetLatestValue
180 */
181  s64 GetUpdateCount(void) const
182  {
183  return m_UpdateCount;
184  }
185 
186 
187 /*!
188 @brief Prints information useful for debugging.
189 
190 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
191 */
192  void Trace(u64 flag) const;
193 
194 
195 private:
196  s64 m_MinValue; // Specifies the minimum value.
197  s64 m_MaxValue; // Specifies the maximum value.
198  s64 m_LatestValue; // Specifies the latest value.
199  u64 m_UpdateCount; // Specifies the number of times the <tt>Update</tt> function has been called.
200 
201  bool m_Enabled; // Specifies whether the <tt>Update</tt> feature is available.
202 
203  char m_Name[MAX_NAME_LENGTH + 1]; // Specifies the name applied to the watermark instance.
204 };
205 }
206 }
207 } // end of namespace nn::pia::common
void Trace(u64 flag) const
Prints information useful for debugging.
s64 GetMaxValue(void) const
Gets the maximum value currently being used by Update.
Definition: common_Watermark.h:149
const char * GetName(void) const
Gets the name of an instance.
Definition: common_Watermark.h:114
Definition: assert.h:115
void EnableUpdate(void)
Enables updating values with the Update function.
Definition: common_Watermark.h:67
Watermark(void)
Instantiates the object with default parameters (default constructor). The instance is constructed wi...
void DisableUpdate(void)
Disables updating values with Update.
Definition: common_Watermark.h:80
void Reset(void)
Re-initializes the values maintained by the instance (maximum, minimum, updated values, and the number of calls to Update).
void SetName(const char *pName)
Sets a name for the instance.
~Watermark(void)
Destroys the object.
static const size_t MAX_NAME_LENGTH
Specifies the maximum length of a name that can be set using the SetName function.
Definition: common_Watermark.h:43
s64 GetMinValue(void) const
Gets the minimum value currently being used by Update.
Definition: common_Watermark.h:160
void Update(s64 value)
Updates the value.
Contains member functions for profiling things like peak values in the Pia library&#39;s resource usage (...
Definition: common_Watermark.h:35
bool IsUpdateEnabled(void) const
Returns whether Update functionality is enabled.
Definition: common_Watermark.h:92
s64 GetUpdateCount(void) const
Gets the number of times Update has been called so far.
Definition: common_Watermark.h:181
This is the common base class used inside the Pia library.
Definition: common_RootObject.h:40
s64 GetLatestValue(void) const
Gets the update value passed in the last call to Update.
Definition: common_Watermark.h:171