Version

menu_open
Wwise SDK 2024.1.0
AkMemoryMgrModule.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  Copyright (c) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// Audiokinetic's definitions and factory of overridable Memory Manager module.
29 
30 #pragma once
31 
36 
37 /// \name Audiokinetic Memory Manager's implementation-specific definitions.
38 //@{
39 
41  );
42 
44  );
45 
47  );
48 
49 typedef void* ( AKSOUNDENGINE_CALL *AkMemMalloc ) (
50  AkMemPoolId poolId,
51  size_t uSize
52  );
53 
54 typedef void* ( AKSOUNDENGINE_CALL *AkMemMalign ) (
55  AkMemPoolId poolId,
56  size_t uSize,
57  AkUInt32 uAlignment
58  );
59 
60 typedef void* ( AKSOUNDENGINE_CALL *AkMemRealloc ) (
61  AkMemPoolId poolId,
62  void* pAddress,
63  size_t uSize
64  );
65 
66 
68  AkMemPoolId poolId,
69  void* pAddress,
70  size_t uSize,
71  AkUInt32 uAlignment
72  );
73 
74 typedef void ( AKSOUNDENGINE_CALL *AkMemFree ) (
75  AkMemPoolId poolId,
76  void* pAddress
77  );
78 
80  );
81 
83  AkMemPoolId poolId,
84  void* pAddress
85  );
86 
88  AkMemPoolId poolId,
89  size_t uSize,
90  void* pAddress,
91  char const* pszFile,
92  AkUInt32 uLine
93  );
94 
96  AkMemPoolId poolId,
97  size_t uSize,
98  AkUInt32 uAlignment,
99  void* pAddress,
100  char const* pszFile,
101  AkUInt32 uLine
102  );
103 
105  AkMemPoolId poolId,
106  void* pOldAddress,
107  size_t uSize,
108  void* pNewAddress,
109  char const* pszFile,
110  AkUInt32 uLine
111  );
112 
114  AkMemPoolId poolId,
115  void* pOldAddress,
116  size_t uSize,
117  AkUInt32 uAlignment,
118  void* pNewAddress,
119  char const* pszFile,
120  AkUInt32 uLine
121  );
122 
124  AkMemPoolId poolId,
125  void* pAddress
126  );
127 
128 // Listing of every memory arena used by the AkMemoryMgr, when using default AkMemoryMgr systems in Wwise
130 {
133  AkMemoryMgrArena_Profiler, // "Profiler" arena will not be available in AK_OPTIMIZED (e.g. "Release") builds
134  AkMemoryMgrArena_Device, // "Device" arena will only be available on platforms that use device memory for voice decoding
136 };
137 
138 namespace AK
139 {
140  namespace MemoryArena
141  {
142  struct AkMemoryArena;
143  }
144 }
145 
146 /// Initialization settings for the default implementation of the Memory Manager. For more details, see \ref memorymanager_init.
147 /// \sa AK::MemoryMgr
149 {
150  /// @name High-level memory allocation hooks. When not NULL, redirect allocations normally forwarded to internal memory systems.
151  //@{
152  AkMemInitForThread pfInitForThread; ///< (Optional) Thread-specific allocator initialization hook.
153  AkMemTermForThread pfTermForThread; ///< (Optional) Thread-specific allocator termination hook.
154  AkMemTrimForThread pfTrimForThread; ///< (Optional) Thread-specific allocator "trimming" hook. Used to relinquish memory resources when threads enter a period of inactivity.
155  AkMemMalloc pfMalloc; ///< (Optional) Memory allocation hook.
156  AkMemMalign pfMalign; ///< (Optional) Memory allocation hook.
157  AkMemRealloc pfRealloc; ///< (Optional) Memory allocation hook.
158  AkMemReallocAligned pfReallocAligned; ///< (Optional) Memory allocation hook.
159  AkMemFree pfFree; ///< (Optional) Memory allocation hook.
160  AkMemTotalReservedMemorySize pfTotalReservedMemorySize; ///< (Optional) Memory allocation statistics hook.
161  AkMemSizeOfMemory pfSizeOfMemory; ///< (Optional) Memory allocation statistics hook.
162  //@}
163 
164  /// @name Configuration.
165  //@{
166  AK::MemoryArena::AkMemoryArenaSettings memoryArenaSettings[AkMemoryMgrArena_NUM]; ///< Configuration of memory arenas for default memory allocator. For more information, see \ref goingfurther_optimizingmempools_memoryarena.
167  AK::TempAlloc::InitSettings tempAllocSettings[AK::TempAlloc::Type_NUM]; ///< Configuration of behavior for the temporary-memory pools. For more information, see \ref goingfurther_optimizingmempools_tempallocs.
168  AK::BookmarkAlloc::InitSettings bookmarkAllocSettings; ///< Configuration of behavior for the bookmark-allocated memory. For more information, see \ref goingfurther_optimizingmempools_bookmarkalloc.
169  //@}
170 
171  /// @name Memory allocation debugging.
172  //@{
173  AkMemDebugMalloc pfDebugMalloc; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfMalloc.
174  AkMemDebugMalign pfDebugMalign; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfMalign.
175  AkMemDebugRealloc pfDebugRealloc; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfRealloc.
176  AkMemDebugReallocAligned pfDebugReallocAligned; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfReallocAligned.
177  AkMemDebugFree pfDebugFree; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfFree.
178  AkUInt32 uMemoryDebugLevel; ///< Default 0 disabled. 1 debug enabled. 2 stomp allocator enabled. 3 stomp allocator and debug enabled. User implementations may use multiple non-zero values to offer different features.
179  //@}
180 };
181 //@}
182 
183 namespace AK
184 {
185 
186 namespace MemoryMgr
187 {
188 
189 /// Initialize the default implementation of the Memory Manager.
190 /// \sa AK::MemoryMgr
192  AkMemSettings * in_pSettings ///< Memory manager initialization settings.
193  );
194 
195 /// Obtain the default initialization settings for the default implementation of the Memory Manager.
197  AkMemSettings & out_pMemSettings ///< Memory manager default initialization settings.
198  );
199 
200 
201 /// Verify the integrity of the book-keeping data of the AkMemoryArena allocator.
202 /// If corruption in the book-keeping data is detected, an assertion failure occurs.
203 /// This function is a no-op if AK_ENABLE_ASSERTS is not defined or if AkMemoryArena has been overridden by custom memory allocations hooks.
205  AkMemoryMgrArena in_eArena /// Which arena to verify
206  );
207 
208 /// Helper to fetch each the arena. Should only be used for debug purposes, e.g. profiling, stats, integrity checks. Returns null in AK_OPTIMIZED builds
209 AK_EXTERNAPIFUNC(AK::MemoryArena::AkMemoryArena*, GetMemoryArena) (
210  AkMemoryMgrArena in_eArena /// Which arena to verify
211  );
212 
213 }
214 
215 }
216 
217 #if defined AK_WIN || defined AK_LINUX || defined AK_SONY || defined AK_XBOX || defined AK_APPLE || defined AK_EMSCRIPTEN
218 #define AK_CRT_ALLOCATOR_SUPPORTED
219 #endif
220 
221 #ifdef AK_CRT_ALLOCATOR_SUPPORTED
222 namespace AK
223 {
224 
225 namespace MemoryMgr
226 {
227 
228 /// @name C runtime allocator functions for the default implementation of the Memory Manager.
229 //@{
230 
232 
234 
236 
238  AkMemPoolId poolId,
239  size_t uSize
240  );
241 
243  AkMemPoolId poolId,
244  size_t uSize,
245  AkUInt32 uAlignment
246  );
247 
249  AkMemPoolId poolId,
250  void* pAddress,
251  size_t uSize
252  );
253 
255  AkMemPoolId poolId,
256  void* pAddress,
257  size_t uSize,
258  AkUInt32 uAlignment
259  );
260 
262  AkMemPoolId poolId,
263  void* pAddress
264  );
265 
267 
269  AkMemPoolId poolID,
270  void* pAddress
271  );
272 
273 //@}
274 
275 }
276 
277 }
278 
279 #endif // AK_CRT_ALLOCATOR_SUPPORTED
280 
281 #if !defined AK_EMSCRIPTEN
282 #define AK_STOMP_ALLOCATOR_SUPPORTED
283 #endif
284 
285 #ifdef AK_STOMP_ALLOCATOR_SUPPORTED
286 
287 namespace AK
288 {
289 
290 namespace MemoryMgr
291 {
292 
293 /// @name Stomp allocator functions for the default implementation of the Memory Manager.
294 //@{
295 
296 AK_EXTERNAPIFUNC( void, AkStompAllocatorInitForThread )();
297 
298 AK_EXTERNAPIFUNC( void, AkStompAllocatorTermForThread )();
299 
300 AK_EXTERNAPIFUNC( void, AkStompAllocatorTrimForThread )();
301 
302 AK_EXTERNAPIFUNC( void*, AkStompAllocatorMalloc )(
303  AkMemPoolId poolId,
304  size_t uSize
305  );
306 
307 AK_EXTERNAPIFUNC( void*, AkStompAllocatorMalign )(
308  AkMemPoolId poolId,
309  size_t uSize,
310  AkUInt32 uAlignment
311  );
312 
313 AK_EXTERNAPIFUNC( void*, AkStompAllocatorRealloc )(
314  AkMemPoolId poolId,
315  void* pAddress,
316  size_t uSize
317  );
318 
319 AK_EXTERNAPIFUNC( void*, AkStompAllocatorReallocAligned )(
320  AkMemPoolId poolId,
321  void* pAddress,
322  size_t uSize,
323  AkUInt32 uAlignment
324  );
325 
326 AK_EXTERNAPIFUNC( void, AkStompAllocatorFree )(
327  AkMemPoolId poolId,
328  void* pAddress
329  );
330 
331 AK_EXTERNAPIFUNC( size_t, AkStompAllocatorTotalReservedMemorySize )();
332 
333 AK_EXTERNAPIFUNC( size_t, AkStompAllocatorSizeOfMemory )(
334  AkMemPoolId poolID,
335  void* pAddress
336  );
337 
338 //@}
339 
340 }
341 
342 }
343 #endif // AK_STOMP_ALLOCATOR_SUPPORTED
344 
345 namespace AK
346 {
347 
348 namespace MemoryMgr
349 {
350 
351 /// @name Debug tool hooks for the default implementation of the Memory Manager.
352 //@{
353 
355 
357 
359  AkMemPoolId poolId,
360  size_t uSize,
361  void* pAddress,
362  char const* pszFile,
363  AkUInt32 uLine
364  );
365 
367  AkMemPoolId poolId,
368  size_t uSize,
369  AkUInt32 uAlignment,
370  void* pAddress,
371  char const* pszFile,
372  AkUInt32 uLine
373  );
374 
376  AkMemPoolId poolId,
377  void* pOldAddress,
378  size_t uSize,
379  void* pNewAddress,
380  char const* pszFile,
381  AkUInt32 uLine
382  );
383 
385  AkMemPoolId poolId,
386  void* pOldAddress,
387  size_t uSize,
388  AkUInt32 uAlignment,
389  void* pNewAddress,
390  char const* pszFile,
391  AkUInt32 uLine
392  );
393 
395  AkMemPoolId poolId,
396  void* pAddress
397  );
398 
399 //@}
400 
401 }
402 
403 }
void *(* AkMemRealloc)(AkMemPoolId poolId, void *pAddress, size_t uSize)
void(* AkMemTermForThread)()
AKSOUNDENGINE_API AKRESULT AkMemDebugToolInit()
AK::MemoryArena::AkMemoryArenaSettings memoryArenaSettings[AkMemoryMgrArena_NUM]
Configuration of memory arenas for default memory allocator. For more information,...
Definition of data structures for AkAudioObject.
AkMemTermForThread pfTermForThread
(Optional) Thread-specific allocator termination hook.
AKSOUNDENGINE_API void AkMemDebugToolMalloc(AkMemPoolId poolId, size_t uSize, void *pAddress, char const *pszFile, AkUInt32 uLine)
AkMemInitForThread pfInitForThread
(Optional) Thread-specific allocator initialization hook.
AkMemFree pfFree
(Optional) Memory allocation hook.
AK::BookmarkAlloc::InitSettings bookmarkAllocSettings
Configuration of behavior for the bookmark-allocated memory. For more information,...
AkMemMalign pfMalign
(Optional) Memory allocation hook.
AKSOUNDENGINE_API AKRESULT Init(AkMemSettings *in_pSettings)
AKSOUNDENGINE_API void AkCrtAllocatorInitForThread()
AkMemoryMgrArena
#define AK_EXTERNAPIFUNC(_type, _name)
AkMemRealloc pfRealloc
(Optional) Memory allocation hook.
AKRESULT
Standard function call result.
Definition: AkTypes.h:134
void(* AkMemInitForThread)()
AKSOUNDENGINE_API void AkMemDebugToolFree(AkMemPoolId poolId, void *pAddress)
size_t(* AkMemSizeOfMemory)(AkMemPoolId poolId, void *pAddress)
AkInt32 AkMemPoolId
Memory pool ID.
Definition: AkTypes.h:62
AkMemDebugRealloc pfDebugRealloc
(Optional) Memory allocation debugging hook. Used for tracking calls to pfRealloc.
AkMemDebugReallocAligned pfDebugReallocAligned
(Optional) Memory allocation debugging hook. Used for tracking calls to pfReallocAligned.
AKSOUNDENGINE_API void AkMemDebugToolTerm()
AKSOUNDENGINE_API void * AkCrtAllocatorMalign(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment)
AkMemTrimForThread pfTrimForThread
(Optional) Thread-specific allocator "trimming" hook. Used to relinquish memory resources when thread...
AKSOUNDENGINE_API void AkMemDebugToolMalign(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment, void *pAddress, char const *pszFile, AkUInt32 uLine)
AKSOUNDENGINE_API AK::MemoryArena::AkMemoryArena * GetMemoryArena(AkMemoryMgrArena in_eArena)
Helper to fetch each the arena. Should only be used for debug purposes, e.g. profiling,...
void(* AkMemDebugRealloc)(AkMemPoolId poolId, void *pOldAddress, size_t uSize, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
AKSOUNDENGINE_API void VerifyMemoryArenaIntegrity(AkMemoryMgrArena in_eArena)
AKSOUNDENGINE_API void AkCrtAllocatorFree(AkMemPoolId poolId, void *pAddress)
AkMemReallocAligned pfReallocAligned
(Optional) Memory allocation hook.
AKSOUNDENGINE_API void * AkCrtAllocatorRealloc(AkMemPoolId poolId, void *pAddress, size_t uSize)
size_t(* AkMemTotalReservedMemorySize)()
AKSOUNDENGINE_API size_t AkCrtAllocatorSizeOfMemory(AkMemPoolId poolID, void *pAddress)
AK::TempAlloc::InitSettings tempAllocSettings[AK::TempAlloc::Type_NUM]
Configuration of behavior for the temporary-memory pools. For more information, see Tuning "Temp Allo...
AKSOUNDENGINE_API void AkMemDebugToolReallocAligned(AkMemPoolId poolId, void *pOldAddress, size_t uSize, AkUInt32 uAlignment, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
AKSOUNDENGINE_API void GetDefaultSettings(AkMemSettings &out_pMemSettings)
Obtain the default initialization settings for the default implementation of the Memory Manager.
@ AkMemoryMgrArena_Primary
void(* AkMemDebugMalign)(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment, void *pAddress, char const *pszFile, AkUInt32 uLine)
AkUInt32 uMemoryDebugLevel
Default 0 disabled. 1 debug enabled. 2 stomp allocator enabled. 3 stomp allocator and debug enabled....
AKSOUNDENGINE_API void * AkCrtAllocatorMalloc(AkMemPoolId poolId, size_t uSize)
#define AKSOUNDENGINE_CALL
Calling convention for the Wwise API.
Definition: AkTypes.h:102
AkMemTotalReservedMemorySize pfTotalReservedMemorySize
(Optional) Memory allocation statistics hook.
AkMemMalloc pfMalloc
(Optional) Memory allocation hook.
void(* AkMemTrimForThread)()
AKSOUNDENGINE_API void AkCrtAllocatorTermForThread()
@ AkMemoryMgrArena_Profiler
@ AkMemoryMgrArena_NUM
void(* AkMemFree)(AkMemPoolId poolId, void *pAddress)
void(* AkMemDebugReallocAligned)(AkMemPoolId poolId, void *pOldAddress, size_t uSize, AkUInt32 uAlignment, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
AkMemDebugMalloc pfDebugMalloc
(Optional) Memory allocation debugging hook. Used for tracking calls to pfMalloc.
@ AkMemoryMgrArena_Media
uint32_t AkUInt32
Unsigned 32-bit integer.
void *(* AkMemReallocAligned)(AkMemPoolId poolId, void *pAddress, size_t uSize, AkUInt32 uAlignment)
@ AkMemoryMgrArena_Device
AKSOUNDENGINE_API size_t AkCrtAllocatorTotalReservedMemorySize()
AKSOUNDENGINE_API void AkCrtAllocatorTrimForThread()
void(* AkMemDebugFree)(AkMemPoolId poolId, void *pAddress)
void(* AkMemDebugMalloc)(AkMemPoolId poolId, size_t uSize, void *pAddress, char const *pszFile, AkUInt32 uLine)
void *(* AkMemMalign)(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment)
AkMemDebugFree pfDebugFree
(Optional) Memory allocation debugging hook. Used for tracking calls to pfFree.
AkMemSizeOfMemory pfSizeOfMemory
(Optional) Memory allocation statistics hook.
AkMemDebugMalign pfDebugMalign
(Optional) Memory allocation debugging hook. Used for tracking calls to pfMalign.
AKSOUNDENGINE_API void AkMemDebugToolRealloc(AkMemPoolId poolId, void *pOldAddress, size_t uSize, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
AKSOUNDENGINE_API void * AkCrtAllocatorReallocAligned(AkMemPoolId poolId, void *pAddress, size_t uSize, AkUInt32 uAlignment)
void *(* AkMemMalloc)(AkMemPoolId poolId, size_t uSize)

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise