Table of Contents

Wwise SDK 2019.2.3
AkMemoryMgr.h
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: <VERSION> Build: <BUILDNUMBER>
25  Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Memory Manager namespace.
30 
31 #ifndef _AKMEMORYMGR_H_
32 #define _AKMEMORYMGR_H_
33 
34 #include <AK/SoundEngine/Common/AkTypes.h>
35 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
36 
37 //#define AK_MEMDEBUG
38 
39 struct AkMemSettings;
40 
41 /// Memory category IDs.
42 enum AkMemID
43 {
44  AkMemID_Object, ///< Generic placeholder for allocations tied to the Wwise project.
45  AkMemID_Event, ///< Events from the Wwise project.
46  AkMemID_Structure, ///< Structures from the Wwise project.
47  AkMemID_Media, ///< Media from the Wwise project.
48  AkMemID_GameObject, ///< Game Objects and related.
49  AkMemID_Processing, ///< Anything tied to instancing and processing of the DSP graph.
50  AkMemID_ProcessingPlugin, ///< Plug-in allocations related to the DSP graph.
51  AkMemID_Streaming, ///< Streaming Manager objects.
52  AkMemID_StreamingIO, ///< Streaming Manager I/O memory.
53  AkMemID_SpatialAudio, ///< Spatial audio.
54  AkMemID_SpatialAudioGeometry, ///< Spatial audio geometry data.
55  AkMemID_SpatialAudioPaths, ///< Spatial audio paths data.
56  AkMemID_GameSim, ///< Game Simulator allocations.
57  AkMemID_MonitorQueue, ///< Monitor Queue.
58  AkMemID_Profiler, ///< Profiler.
59  AkMemID_FilePackage, ///< File packager.
60  AkMemID_SoundEngine, ///< Base sound engine allocations (managers, etc).
61 
62  AkMemID_NUM, ///< Category count.
63  AkMemID_MASK = 0x7FFFFFFF, ///< Mask for category IDs.
64 
65  AkMemType_Device = 0x80000000 ///< Device memory type bit.
66 };
67 
68 namespace AK
69 {
70  /// Memory Manager namespace.
71  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
72  /// \sa
73  /// - \ref memorymanager
74  namespace MemoryMgr
75  {
76  /// Memory category statistics.
77  /// \remarks These statistics are not collected in the Release configuration of
78  /// the default memory manager implementation.
79  /// \sa
80  /// - AK::MemoryMgr::GetCategoryStats()
81  /// - \ref memorymanager
82  struct CategoryStats
83  {
84  // Current state
85  AkUInt64 uUsed; ///< Used memory (in bytes)
86 
87  // Statistics
88  AkUInt64 uPeakUsed; ///< Peak used memory (in bytes)
89  AkUInt32 uAllocs; ///< Number of allocation calls since initialization
90  AkUInt32 uFrees; ///< Number of free calls since initialization
91  };
92 
93  struct GlobalStats
94  {
95  AkUInt64 uUsed;
96  AkUInt64 uDeviceUsed;
97  AkUInt64 uReserved;
98  AkUInt64 uMax;
99  };
100 
101  ////////////////////////////////////////////////////////////////////////
102  /// @name Initialization
103  //@{
104 
105  /// Query whether the Memory Manager has been sucessfully initialized.
106  /// \warning This function is not thread-safe. It should not be called at the same time as MemoryMgr::Init or MemoryMgr::Term.
107  /// \return True if the Memory Manager is initialized, False otherwise
108  /// \sa
109  /// - AK::MemoryMgr::Init()
110  /// - \ref memorymanager
111  AK_EXTERNAPIFUNC( bool, IsInitialized )();
112 
113  /// Terminate the Memory Manager.
114  /// \warning This function is not thread-safe. It is not valid to allocate memory or otherwise interact with the memory manager during or after this call.
115  /// \sa
116  /// - \ref memorymanager
117  AK_EXTERNAPIFUNC( void, Term )();
118 
119  /// Performs whatever steps are required to initialize a thread for use with the memory manager.
120  /// For example initializing thread local storage that the allocator requires to work.
121  /// The default implementation of the memory manager performs thread initialization automatically and therefore this call is optional.
122  /// For implementations where the cost of automatically initializing a thread for use with an allocator would be prohibitively expensive
123  /// this call allows you to perform the initialization once during, for example, thread creation.
124  /// \sa
125  /// - AkMemInitForThread
126  AK_EXTERNAPIFUNC( void, InitForThread )();
127 
128  /// Allows you to manually terminate a thread for use with the memory manager.
129  /// The default implementation of the memory manager requires that all threads that interact with the memory manager call this function prior
130  /// to either their termination or the termination of the memory manager. Threads not created by the sound engine itself will not have this
131  /// function called for them automatically.
132  /// Take care to call this function for any thread, not owned by wwise, that may have interacted with the memory manager. For example job system workers.
133  /// \sa
134  /// - AkMemTermForThread
135  AK_EXTERNAPIFUNC( void, TermForThread )();
136 
137  //@}
138 
139  ////////////////////////////////////////////////////////////////////////
140  /// @name Memory Allocation
141  //@{
142 
143 #if defined (AK_MEMDEBUG)
144  /// Allocate memory: debug version.
145  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
146  /// \sa
147  /// - \ref memorymanager
148  AK_EXTERNAPIFUNC( void *, dMalloc )(
149  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
150  size_t in_uSize, ///< Number of bytes to allocate
151  const char *in_pszFile, ///< Debug file name
152  AkUInt32 in_uLine ///< Debug line number
153  );
154 #endif
155  /// Allocate memory.
156  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
157  /// \sa
158  /// - \ref memorymanager
159  AK_EXTERNAPIFUNC( void *, Malloc )(
160  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
161  size_t in_uSize ///< Number of bytes to allocate
162  );
163 
164 #if defined (AK_MEMDEBUG)
165  /// Reallocate memory: debug version.
166  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
167  /// \sa
168  /// - \ref memorymanager
169  AK_EXTERNAPIFUNC( void*, dRealloc )(
170  AkMemPoolId in_poolId,
171  void *in_pAlloc,
172  size_t in_uSize,
173  const char *in_pszFile,
174  AkUInt32 in_uLine
175  );
176 #endif
177 
178  /// Reallocate memory.
179  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
180  /// \sa
181  /// - \ref memorymanager
182  AK_EXTERNAPIFUNC( void *, Realloc )(
183  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
184  void * in_pAlloc, ///< Pointer to the start of the allocated memory
185  size_t in_uSize ///< Number of bytes to allocate
186  );
187 
188  /// Free memory allocated with either AK::MemoryMgr::Malloc or AKMemoryMgr::Realloc.
189  /// \sa
190  /// - \ref memorymanager
191  AK_EXTERNAPIFUNC( void, Free )(
192  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
193  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc or Realloc
194  );
195 
196 #if defined (AK_MEMDEBUG)
197  /// Allocate memory with a specific alignment. Needs to be used
198  /// in conjunction with AK::MemoryMgr::Falign. debug version.
199  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
200  /// \sa
201  /// - \ref memorymanager
202  AK_EXTERNAPIFUNC( void *, dMalign )(
203  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
204  size_t in_uSize, ///< Number of bytes to allocate
205  AkUInt32 in_uAlignment, ///< Alignment (in bytes)
206  const char* in_pszFile, ///< Debug file name
207  AkUInt32 in_uLine ///< Debug line number
208  );
209 #endif
210 
211  /// Allocate memory with a specific alignment. Needs to be used
212  /// in conjunction with AK::MemoryMgr::Falign.
213  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
214  /// \sa
215  /// - \ref memorymanager
216  AK_EXTERNAPIFUNC( void *, Malign )(
217  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
218  size_t in_uSize, ///< Number of bytes to allocate
219  AkUInt32 in_uAlignment ///< Alignment (in bytes)
220  );
221 
222  /// Free memory allocated with AK::MemoryMgr::Malign.
223  /// \sa
224  /// - \ref memorymanager
225  AK_EXTERNAPIFUNC( void, Falign )(
226  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
227  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malign
228  );
229 
230  //@}
231 
232  ////////////////////////////////////////////////////////////////////////
233  /// @name Memory Profiling
234  //@{
235 
236  /// Get statistics for a given memory category.
237  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
238  AK_EXTERNAPIFUNC( void, GetCategoryStats )(
239  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
240  CategoryStats& out_poolStats ///< Returned statistics.
241  );
242 
243  /// Get statistics for overall memory manager usage.
244  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
245  AK_EXTERNAPIFUNC( void, GetGlobalStats )(
246  GlobalStats& out_stats ///< Returned statistics.
247  );
248 
249  /// Called to start profiling memory usage for one thread (the calling thread).
250  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
251  AK_EXTERNAPIFUNC( void, StartProfileThreadUsage )(
252  );
253 
254  /// Called to stop profiling memory usage for the current thread.
255  /// \return The amount of memory allocated by this thread since StartProfileThreadUsage was called.
256  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
257  AK_EXTERNAPIFUNC( AkUInt64, StopProfileThreadUsage )(
258  );
259 
260  //@}
261  }
262 }
263 
264 #endif // _AKMEMORYMGR_H_
AkUInt64 uPeakUsed
Peak used memory (in bytes)
Definition: AkMemoryMgr.h:88
Audiokinetic namespace.
AKSOUNDENGINE_API void __cdecl Term()
AkUInt32 uAllocs
Number of allocation calls since initialization.
Definition: AkMemoryMgr.h:89
AKSOUNDENGINE_API void __cdecl Falign(AkMemPoolId in_poolId, void *in_pMemAddress)
AKSOUNDENGINE_API void __cdecl TermForThread()
AKSOUNDENGINE_API void *__cdecl Malign(AkMemPoolId in_poolId, size_t in_uSize, AkUInt32 in_uAlignment)
AKSOUNDENGINE_API void __cdecl InitForThread()
AKSOUNDENGINE_API void *__cdecl Realloc(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize)
AKSOUNDENGINE_API void __cdecl StartProfileThreadUsage()
AkUInt64 uUsed
Used memory (in bytes)
Definition: AkMemoryMgr.h:85
AKSOUNDENGINE_API void __cdecl Free(AkMemPoolId in_poolId, void *in_pMemAddress)
AKSOUNDENGINE_API void *__cdecl Malloc(AkMemPoolId in_poolId, size_t in_uSize)
AKSOUNDENGINE_API void __cdecl GetCategoryStats(AkMemPoolId in_poolId, CategoryStats &out_poolStats)
AKSOUNDENGINE_API AkUInt64 __cdecl StopProfileThreadUsage()
AKSOUNDENGINE_API void __cdecl GetGlobalStats(GlobalStats &out_stats)
AKSOUNDENGINE_API bool __cdecl IsInitialized()
AkUInt32 uFrees
Number of free calls since initialization.
Definition: AkMemoryMgr.h:90