Wwise Version
Wwise SDK 2021.1.3
AkMemoryMgr.h
Go to the documentation of this file.
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: v2021.1.3 Build: 7665
25  Copyright (c) 2006-2021 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /// \file
29 /// Memory Manager namespace.
30 
31 #ifndef _AKMEMORYMGR_H_
32 #define _AKMEMORYMGR_H_
33 
34 #if !defined( AK_OPTIMIZED ) && !( defined AK_DISABLE_MEMDEBUG )
35  #ifndef AK_MEMDEBUG
36  #define AK_MEMDEBUG
37  #endif
38 #endif
39 
42 
43 struct AkMemSettings;
44 
45 /// Memory category IDs.
46 enum AkMemID
47 {
48  AkMemID_Object, ///< Generic placeholder for allocations tied to the Wwise project.
49  AkMemID_Event, ///< Events from the Wwise project.
50  AkMemID_Structure, ///< Structures from the Wwise project.
51  AkMemID_Media, ///< Media from the Wwise project.
52  AkMemID_GameObject, ///< Game Objects and related.
53  AkMemID_Processing, ///< Anything tied to instancing and processing of the DSP graph.
54  AkMemID_ProcessingPlugin, ///< Plug-in allocations related to the DSP graph.
55  AkMemID_Streaming, ///< Streaming Manager objects.
56  AkMemID_StreamingIO, ///< Streaming Manager I/O memory.
57  AkMemID_SpatialAudio, ///< Spatial audio.
58  AkMemID_SpatialAudioGeometry, ///< Spatial audio geometry data.
59  AkMemID_SpatialAudioPaths, ///< Spatial audio paths data.
60  AkMemID_GameSim, ///< Game Simulator allocations.
61  AkMemID_MonitorQueue, ///< Monitor Queue.
62  AkMemID_Profiler, ///< Profiler.
63  AkMemID_FilePackage, ///< File packager.
64  AkMemID_SoundEngine, ///< Base sound engine allocations (managers, etc).
65  AkMemID_Integration, ///< Game engine integration allocations.
66 
67  AkMemID_NUM, ///< Category count.
68  AkMemID_MASK = 0x1FFFFFFF, ///< Mask for category IDs.
69 
70  AkMemType_Media = 0x20000000, ///< Media memory type bit.
71  AkMemType_Device = 0x40000000, ///< Device memory type bit.
72  AkMemType_NoTrack = 0x80000000 ///< Do not track this allocation.
73 };
74 
75 namespace AK
76 {
77  /// Memory Manager namespace.
78  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
79  /// \sa
80  /// - \ref memorymanager
81  namespace MemoryMgr
82  {
83  /// Memory category statistics.
84  /// \remarks These statistics are not collected in the Release configuration of
85  /// the default memory manager implementation.
86  /// \sa
87  /// - AK::MemoryMgr::GetCategoryStats()
88  /// - \ref memorymanager
89  struct CategoryStats
90  {
91  // Current state
92  AkUInt64 uUsed; ///< Used memory (in bytes)
93 
94  // Statistics
95  AkUInt64 uPeakUsed; ///< Peak used memory (in bytes)
96  AkUInt32 uAllocs; ///< Number of allocation calls since initialization
97  AkUInt32 uFrees; ///< Number of free calls since initialization
98  };
99 
100  /// Memory global statistics.
101  /// \remarks These statistics are not collected in the Release configuration of
102  /// the default memory manager implementation.
103  /// \sa
104  /// - AK::MemoryMgr::GetGlobalStats()
105  /// - \ref memorymanager
106  struct GlobalStats
107  {
108  AkUInt64 uUsed; ///< Total memory used including all categories (in bytes)
109  AkUInt64 uDeviceUsed; ///< Total device memory used including all categories (in bytes)
110  AkUInt64 uReserved; ///< Total reserved memory. (Used and unused). Will return 0 if the reserved memory is not traceable.
111  AkUInt64 uMax; ///< Maximum total allocation size, specified in the initialization settings through uMemAllocationSizeLimit. Will be 0 if no limit was set.
112  };
113 
114  ////////////////////////////////////////////////////////////////////////
115  /// @name Initialization
116  //@{
117 
118  /// Query whether the Memory Manager has been sucessfully initialized.
119  /// \warning This function is not thread-safe. It should not be called at the same time as MemoryMgr::Init or MemoryMgr::Term.
120  /// \return True if the Memory Manager is initialized, False otherwise
121  /// \sa
122  /// - AK::MemoryMgr::Init()
123  /// - \ref memorymanager
125 
126  /// Terminate the Memory Manager.
127  /// \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.
128  /// \sa
129  /// - \ref memorymanager
130  AK_EXTERNAPIFUNC( void, Term )();
131 
132  /// Performs whatever steps are required to initialize a thread for use with the memory manager.
133  /// For example initializing thread local storage that the allocator requires to work.
134  /// The default implementation of the memory manager performs thread initialization automatically and therefore this call is optional.
135  /// For implementations where the cost of automatically initializing a thread for use with an allocator would be prohibitively expensive
136  /// this call allows you to perform the initialization once during, for example, thread creation.
137  /// \sa
138  /// - AkMemInitForThread
140 
141  /// Allows you to manually terminate a thread for use with the memory manager.
142  /// The default implementation of the memory manager requires that all threads that interact with the memory manager call this function prior
143  /// to either their termination or the termination of the memory manager. Threads not created by the sound engine itself will not have this
144  /// function called for them automatically.
145  /// 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.
146  /// \sa
147  /// - AkMemTermForThread
149 
150  //@}
151 
152  ////////////////////////////////////////////////////////////////////////
153  /// @name Memory Allocation
154  //@{
155 
156 #ifdef AK_MEMDEBUG
157  /// Allocate memory: debug version.
158  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
159  /// \sa
160  /// - \ref memorymanager
162  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
163  size_t in_uSize, ///< Number of bytes to allocate
164  const char *in_pszFile, ///< Debug file name
165  AkUInt32 in_uLine ///< Debug line number
166  );
167 #endif // AK_MEMDEBUG
168 
169  /// Allocate memory.
170  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
171  /// \sa
172  /// - \ref memorymanager
174  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
175  size_t in_uSize ///< Number of bytes to allocate
176  );
177 
178 #ifdef AK_MEMDEBUG
179  /// Reallocate memory: debug version.
180  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
181  /// \sa
182  /// - \ref memorymanager
184  AkMemPoolId in_poolId,
185  void *in_pAlloc,
186  size_t in_uSize,
187  const char *in_pszFile,
188  AkUInt32 in_uLine
189  );
190 #endif // AK_MEMDEBUG
191 
192  /// Reallocate memory.
193  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
194  /// \sa
195  /// - \ref memorymanager
197  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
198  void * in_pAlloc, ///< Pointer to the start of the allocated memory
199  size_t in_uSize ///< Number of bytes to allocate
200  );
201 
202 #ifdef AK_MEMDEBUG
203  /// Reallocate memory: debug version.
204  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
205  /// \sa
206  /// - \ref memorymanager
208  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
209  void *in_pAlloc, ///< Pointer to the start of the allocated memory
210  size_t in_uSize, ///< Number of bytes to allocate
211  AkUInt32 in_uAlignment, ///< Alignment (in bytes)
212  const char *in_pszFile, ///< Debug file name
213  AkUInt32 in_uLine ///< Debug line number
214  );
215 #endif // AK_MEMDEBUG
216 
217  /// Reallocate memory.
218  /// \return A pointer to the start of the reallocated memory (NULL if the allocation could not be completed)
219  /// \sa
220  /// - \ref memorymanager
222  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
223  void * in_pAlloc, ///< Pointer to the start of the allocated memory
224  size_t in_uSize, ///< Number of bytes to allocate
225  AkUInt32 in_uAlignment ///< Alignment (in bytes)
226  );
227 
228  /// Free memory allocated with the memory manager.
229  /// \sa
230  /// - \ref memorymanager
232  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
233  void * in_pMemAddress ///< Pointer to the start of memory
234  );
235 
236 #ifdef AK_MEMDEBUG
237  /// Allocate memory with a specific alignment. debug version.
238  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
239  /// \sa
240  /// - \ref memorymanager
242  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
243  size_t in_uSize, ///< Number of bytes to allocate
244  AkUInt32 in_uAlignment, ///< Alignment (in bytes)
245  const char* in_pszFile, ///< Debug file name
246  AkUInt32 in_uLine ///< Debug line number
247  );
248 #endif // AK_MEMDEBUG
249 
250  /// Allocate memory with a specific alignment.
251  /// \return A pointer to the start of the allocated memory (NULL if the allocation could not be completed)
252  /// \sa
253  /// - \ref memorymanager
255  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
256  size_t in_uSize, ///< Number of bytes to allocate
257  AkUInt32 in_uAlignment ///< Alignment (in bytes)
258  );
259 
260  //@}
261 
262  ////////////////////////////////////////////////////////////////////////
263  /// @name Memory Profiling
264  //@{
265 
266  /// Get statistics for a given memory category.
267  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
269  AkMemPoolId in_poolId, ///< ID of the memory category (AkMemID)
270  CategoryStats& out_poolStats ///< Returned statistics.
271  );
272 
273  /// Get statistics for overall memory manager usage.
274  /// \note Be aware of the potentially incoherent nature of reporting such information during concurrent modification by multiple threads.
276  GlobalStats& out_stats ///< Returned statistics.
277  );
278 
279  /// Called to start profiling memory usage for one thread (the calling thread).
280  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
282  );
283 
284  /// Called to stop profiling memory usage for the current thread.
285  /// \return The amount of memory allocated by this thread since StartProfileThreadUsage was called.
286  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
288  );
289 
290  /// Dumps the currently tracked allocations to a file
291  /// \note AkMemSettings::uMemoryDebugLevel must be enabled and the build must define AK_MEMDEBUG for this to work
293  const AkOSChar* pszFilename ///< Filename.
294  );
295 
296  //@}
297  }
298 }
299 
300 #endif // _AKMEMORYMGR_H_
@ AkMemID_Processing
Anything tied to instancing and processing of the DSP graph.
Definition: AkMemoryMgr.h:53
AKSOUNDENGINE_API void DumpToFile(const AkOSChar *pszFilename)
@ AkMemID_SpatialAudioPaths
Spatial audio paths data.
Definition: AkMemoryMgr.h:59
@ AkMemID_MonitorQueue
Monitor Queue.
Definition: AkMemoryMgr.h:61
@ AkMemID_FilePackage
File packager.
Definition: AkMemoryMgr.h:63
AKSOUNDENGINE_API void TermForThread()
AKSOUNDENGINE_API void * dRealloc(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize, const char *in_pszFile, AkUInt32 in_uLine)
AkUInt64 uPeakUsed
Peak used memory (in bytes)
Definition: AkMemoryMgr.h:95
AkUInt64 uDeviceUsed
Total device memory used including all categories (in bytes)
Definition: AkMemoryMgr.h:109
Audiokinetic namespace.
@ AkMemID_StreamingIO
Streaming Manager I/O memory.
Definition: AkMemoryMgr.h:56
AKSOUNDENGINE_API void * dMalloc(AkMemPoolId in_poolId, size_t in_uSize, const char *in_pszFile, AkUInt32 in_uLine)
@ AkMemID_Media
Media from the Wwise project.
Definition: AkMemoryMgr.h:51
@ AkMemID_Integration
Game engine integration allocations.
Definition: AkMemoryMgr.h:65
@ AkMemID_Object
Generic placeholder for allocations tied to the Wwise project.
Definition: AkMemoryMgr.h:48
AKSOUNDENGINE_API void * dMalign(AkMemPoolId in_poolId, size_t in_uSize, AkUInt32 in_uAlignment, const char *in_pszFile, AkUInt32 in_uLine)
AKSOUNDENGINE_API void Free(AkMemPoolId in_poolId, void *in_pMemAddress)
#define AK_EXTERNAPIFUNC(_type, _name)
AKSOUNDENGINE_API void * Malloc(AkMemPoolId in_poolId, size_t in_uSize)
AkInt32 AkMemPoolId
Memory pool ID.
Definition: AkTypes.h:67
@ AkMemID_Profiler
Profiler.
Definition: AkMemoryMgr.h:62
AkMemID
Memory category IDs.
Definition: AkMemoryMgr.h:47
char AkOSChar
Generic character string.
Definition: AkTypes.h:66
AkUInt32 uAllocs
Number of allocation calls since initialization.
Definition: AkMemoryMgr.h:96
AKSOUNDENGINE_API void Term()
AKSOUNDENGINE_API void GetGlobalStats(GlobalStats &out_stats)
AKSOUNDENGINE_API void InitForThread()
@ AkMemID_SpatialAudioGeometry
Spatial audio geometry data.
Definition: AkMemoryMgr.h:58
AkUInt64 uReserved
Total reserved memory. (Used and unused). Will return 0 if the reserved memory is not traceable.
Definition: AkMemoryMgr.h:110
uint64_t AkUInt64
Unsigned 64-bit integer.
Definition: AkTypes.h:58
AkUInt64 uMax
Maximum total allocation size, specified in the initialization settings through uMemAllocationSizeLim...
Definition: AkMemoryMgr.h:111
AKSOUNDENGINE_API void * dReallocAligned(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize, AkUInt32 in_uAlignment, const char *in_pszFile, AkUInt32 in_uLine)
AKSOUNDENGINE_API void * Malign(AkMemPoolId in_poolId, size_t in_uSize, AkUInt32 in_uAlignment)
@ AkMemID_SoundEngine
Base sound engine allocations (managers, etc).
Definition: AkMemoryMgr.h:64
AKSOUNDENGINE_API void StartProfileThreadUsage()
@ AkMemID_GameSim
Game Simulator allocations.
Definition: AkMemoryMgr.h:60
@ AkMemID_GameObject
Game Objects and related.
Definition: AkMemoryMgr.h:52
@ AkMemID_Streaming
Streaming Manager objects.
Definition: AkMemoryMgr.h:55
@ AkMemID_NUM
Category count.
Definition: AkMemoryMgr.h:67
@ AkMemID_MASK
Mask for category IDs.
Definition: AkMemoryMgr.h:68
AKSOUNDENGINE_API void * Realloc(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize)
@ AkMemID_Structure
Structures from the Wwise project.
Definition: AkMemoryMgr.h:50
@ AkMemID_Event
Events from the Wwise project.
Definition: AkMemoryMgr.h:49
AKSOUNDENGINE_API AkUInt64 StopProfileThreadUsage()
AkUInt64 uUsed
Total memory used including all categories (in bytes)
Definition: AkMemoryMgr.h:108
AkUInt64 uUsed
Used memory (in bytes)
Definition: AkMemoryMgr.h:92
@ AkMemID_ProcessingPlugin
Plug-in allocations related to the DSP graph.
Definition: AkMemoryMgr.h:54
AKSOUNDENGINE_API void GetCategoryStats(AkMemPoolId in_poolId, CategoryStats &out_poolStats)
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:57
@ AkMemType_NoTrack
Do not track this allocation.
Definition: AkMemoryMgr.h:72
AKSOUNDENGINE_API bool IsInitialized()
@ AkMemID_SpatialAudio
Spatial audio.
Definition: AkMemoryMgr.h:57
AKSOUNDENGINE_API void * ReallocAligned(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize, AkUInt32 in_uAlignment)
@ AkMemType_Device
Device memory type bit.
Definition: AkMemoryMgr.h:71
@ AkMemType_Media
Media memory type bit.
Definition: AkMemoryMgr.h:70
AkUInt32 uFrees
Number of free calls since initialization.
Definition: AkMemoryMgr.h:97