Version
menu_open
link
Wwise SDK 2023.1.4
AkModule.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 
34 
35 /// \name Audiokinetic Memory Manager's implementation-specific definitions.
36 //@{
37 
39  );
40 
42  );
43 
45  );
46 
47 typedef void* ( AKSOUNDENGINE_CALL *AkMemMalloc ) (
48  AkMemPoolId poolId,
49  size_t uSize
50  );
51 
52 typedef void* ( AKSOUNDENGINE_CALL *AkMemMalign ) (
53  AkMemPoolId poolId,
54  size_t uSize,
55  AkUInt32 uAlignment
56  );
57 
58 typedef void* ( AKSOUNDENGINE_CALL *AkMemRealloc ) (
59  AkMemPoolId poolId,
60  void* pAddress,
61  size_t uSize
62  );
63 
64 
66  AkMemPoolId poolId,
67  void* pAddress,
68  size_t uSize,
69  AkUInt32 uAlignment
70  );
71 
72 typedef void ( AKSOUNDENGINE_CALL *AkMemFree ) (
73  AkMemPoolId poolId,
74  void* pAddress
75  );
76 
78  );
79 
81  AkMemPoolId poolId,
82  void* pAddress
83  );
84 
86  AkMemPoolId poolId,
87  size_t uSize,
88  void* pAddress,
89  char const* pszFile,
90  AkUInt32 uLine
91  );
92 
94  AkMemPoolId poolId,
95  size_t uSize,
96  AkUInt32 uAlignment,
97  void* pAddress,
98  char const* pszFile,
99  AkUInt32 uLine
100  );
101 
103  AkMemPoolId poolId,
104  void* pOldAddress,
105  size_t uSize,
106  void* pNewAddress,
107  char const* pszFile,
108  AkUInt32 uLine
109  );
110 
112  AkMemPoolId poolId,
113  void* pOldAddress,
114  size_t uSize,
115  AkUInt32 uAlignment,
116  void* pNewAddress,
117  char const* pszFile,
118  AkUInt32 uLine
119  );
120 
122  AkMemPoolId poolId,
123  void* pAddress
124  );
125 
126 typedef void* ( *AkMemAllocVM ) (
127  size_t size,
128  size_t* extra
129  );
130 
131 typedef void ( *AkMemFreeVM ) (
132  void* address,
133  size_t size,
134  size_t extra,
135  size_t release
136  );
137 
139 {
140  // Span count attempts to be as low as possible. Offers lowest memory usage, but reduces CPU performance due to increased calls to pfAllocVM and other memory allocation hooks.
142 
143  // Span count attempts to match 512KiB mappings. Offers moderate balance between memory and CPU usage.
145 
146  // Span count attempts to match 2MiB, or AK_VM_HUGE_PAGE_SIZE, mappings. Offers best overall CPU performance due to use of 2MiB page mappings, but increased memory usage.
148 
150 };
151 
152 /// Initialization settings for the default implementation of the Memory Manager. For more details, see \ref memorymanager_init.
153 /// \sa AK::MemoryMgr
155 {
156  /// @name High-level memory allocation hooks. When not NULL, redirect allocations normally forwarded to rpmalloc.
157  //@{
158  AkMemInitForThread pfInitForThread; ///< (Optional) Thread-specific allocator initialization hook.
159  AkMemTermForThread pfTermForThread; ///< (Optional) Thread-specific allocator termination hook.
160  AkMemTrimForThread pfTrimForThread; ///< (Optional) Thread-specific allocator "trimming" hook. Used to relinquish memory resources when threads enter a period of inactivity.
161  AkMemMalloc pfMalloc; ///< (Optional) Memory allocation hook.
162  AkMemMalign pfMalign; ///< (Optional) Memory allocation hook.
163  AkMemRealloc pfRealloc; ///< (Optional) Memory allocation hook.
164  AkMemReallocAligned pfReallocAligned; ///< (Optional) Memory allocation hook.
165  AkMemFree pfFree; ///< (Optional) Memory allocation hook.
166  AkMemTotalReservedMemorySize pfTotalReservedMemorySize; ///< (Optional) Memory allocation statistics hook.
167  AkMemSizeOfMemory pfSizeOfMemory; ///< (Optional) Memory allocation statistics hook.
168  //@}
169 
170  /// @name Configuration.
171  //@{
172  AkUInt64 uMemAllocationSizeLimit; ///< When non-zero, limits the total amount of virtual and device memory allocated by AK::MemoryMgr.
173  bool bEnableSeparateDeviceHeap; ///< Enable use of device memory heap for all allocations (on applicable platforms).
174  AK::TempAlloc::InitSettings tempAllocSettings[AK::TempAlloc::Type_NUM]; ///< Configuration of behavior for the temporary-memory pools. For more information, see \ref goingfurther_optimizingmempools_tempallocs.
175  //@}
176 
177  /// @name Page allocation hooks, used by rpmalloc. Default to AKPLATFORM::AllocVM et al.
178  //@{
179  AkMemAllocVM pfAllocVM; ///< Virtual page allocation hook.
180  AkMemFreeVM pfFreeVM; ///< Virtual page allocation hook.
181  AkMemAllocVM pfAllocDevice; ///< Device page allocation hook.
182  AkMemFreeVM pfFreeDevice; ///< Device page allocation hook.
183  AkUInt32 uVMPageSize; ///< Virtual memory page size. Defaults to 0 which means auto-detect.
184  AkUInt32 uDevicePageSize; ///< Device memory page size. Defaults to 0 which means auto-detect.
185  //AkSpanCount uVMSpanCount; ///< Virtual memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge. For more information, refer to \ref goingfurther_optimizingmempools_spancount.
186  //AkSpanCount uDeviceSpanCount; ///< Device memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge. For more information, refer to \ref goingfurther_optimizingmempools_spancount.
187  AkUInt32 uMaxThreadLocalHeapAllocSize; ///< All memory allocations of sizes larger than this value will go to a global heap shared across all threads. Defaults to 0 which means all allocations go to a global heap.
188  //@}
189 
190  /// @name Memory allocation debugging.
191  //@{
192  AkMemDebugMalloc pfDebugMalloc; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfMalloc.
193  AkMemDebugMalign pfDebugMalign; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfMalign.
194  AkMemDebugRealloc pfDebugRealloc; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfRealloc.
195  AkMemDebugReallocAligned pfDebugReallocAligned; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfReallocAligned.
196  AkMemDebugFree pfDebugFree; ///< (Optional) Memory allocation debugging hook. Used for tracking calls to pfFree.
197  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.
198  //@}
199 
200  // Moved to end-of-struct to maintain stability across 2023.1 modules.
201  AkSpanCount uVMSpanCount; ///< Virtual memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge. For more information, refer to \ref goingfurther_optimizingmempools_spancount.
202  AkSpanCount uDeviceSpanCount; ///< Device memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge. For more information, refer to \ref goingfurther_optimizingmempools_spancount.
203 
204 };
205 //@}
206 
207 namespace AK
208 {
209 
210 namespace MemoryMgr
211 {
212 
213 /// Initialize the default implementation of the Memory Manager.
214 /// \sa AK::MemoryMgr
216  AkMemSettings * in_pSettings ///< Memory manager initialization settings.
217  );
218 
219 /// Obtain the default initialization settings for the default implementation of the Memory Manager.
221  AkMemSettings & out_pMemSettings ///< Memory manager default initialization settings.
222  );
223 
224 }
225 
226 }
227 
228 #if defined AK_WIN || defined AK_LINUX || defined AK_SONY || defined AK_XBOX || defined AK_APPLE || defined AK_EMSCRIPTEN
229 #define AK_CRT_ALLOCATOR_SUPPORTED
230 #endif
231 
232 #ifdef AK_CRT_ALLOCATOR_SUPPORTED
233 namespace AK
234 {
235 
236 namespace MemoryMgr
237 {
238 
239 /// @name C runtime allocator functions for the default implementation of the Memory Manager.
240 //@{
241 
243 
245 
247 
249  AkMemPoolId poolId,
250  size_t uSize
251  );
252 
254  AkMemPoolId poolId,
255  size_t uSize,
256  AkUInt32 uAlignment
257  );
258 
260  AkMemPoolId poolId,
261  void* pAddress,
262  size_t uSize
263  );
264 
266  AkMemPoolId poolId,
267  void* pAddress,
268  size_t uSize,
269  AkUInt32 uAlignment
270  );
271 
273  AkMemPoolId poolId,
274  void* pAddress
275  );
276 
278 
280  AkMemPoolId poolID,
281  void* pAddress
282  );
283 
284 //@}
285 
286 }
287 
288 }
289 
290 #endif // AK_CRT_ALLOCATOR_SUPPORTED
291 
292 #if !defined AK_EMSCRIPTEN
293 #define AK_STOMP_ALLOCATOR_SUPPORTED
294 #endif
295 
296 #ifdef AK_STOMP_ALLOCATOR_SUPPORTED
297 
298 namespace AK
299 {
300 
301 namespace MemoryMgr
302 {
303 
304 /// @name Stomp allocator functions for the default implementation of the Memory Manager.
305 //@{
306 
307 AK_EXTERNAPIFUNC( void, AkStompAllocatorInitForThread )();
308 
309 AK_EXTERNAPIFUNC( void, AkStompAllocatorTermForThread )();
310 
311 AK_EXTERNAPIFUNC( void, AkStompAllocatorTrimForThread )();
312 
313 AK_EXTERNAPIFUNC( void*, AkStompAllocatorMalloc )(
314  AkMemPoolId poolId,
315  size_t uSize
316  );
317 
318 AK_EXTERNAPIFUNC( void*, AkStompAllocatorMalign )(
319  AkMemPoolId poolId,
320  size_t uSize,
321  AkUInt32 uAlignment
322  );
323 
324 AK_EXTERNAPIFUNC( void*, AkStompAllocatorRealloc )(
325  AkMemPoolId poolId,
326  void* pAddress,
327  size_t uSize
328  );
329 
330 AK_EXTERNAPIFUNC( void*, AkStompAllocatorReallocAligned )(
331  AkMemPoolId poolId,
332  void* pAddress,
333  size_t uSize,
334  AkUInt32 uAlignment
335  );
336 
337 AK_EXTERNAPIFUNC( void, AkStompAllocatorFree )(
338  AkMemPoolId poolId,
339  void* pAddress
340  );
341 
342 AK_EXTERNAPIFUNC( size_t, AkStompAllocatorTotalReservedMemorySize )();
343 
344 AK_EXTERNAPIFUNC( size_t, AkStompAllocatorSizeOfMemory )(
345  AkMemPoolId poolID,
346  void* pAddress
347  );
348 
349 //@}
350 
351 }
352 
353 }
354 #endif // AK_STOMP_ALLOCATOR_SUPPORTED
355 
356 namespace AK
357 {
358 
359 namespace MemoryMgr
360 {
361 
362 /// @name Debug tool hooks for the default implementation of the Memory Manager.
363 //@{
364 
366 
368 
370  AkMemPoolId poolId,
371  size_t uSize,
372  void* pAddress,
373  char const* pszFile,
374  AkUInt32 uLine
375  );
376 
378  AkMemPoolId poolId,
379  size_t uSize,
380  AkUInt32 uAlignment,
381  void* pAddress,
382  char const* pszFile,
383  AkUInt32 uLine
384  );
385 
387  AkMemPoolId poolId,
388  void* pOldAddress,
389  size_t uSize,
390  void* pNewAddress,
391  char const* pszFile,
392  AkUInt32 uLine
393  );
394 
396  AkMemPoolId poolId,
397  void* pOldAddress,
398  size_t uSize,
399  AkUInt32 uAlignment,
400  void* pNewAddress,
401  char const* pszFile,
402  AkUInt32 uLine
403  );
404 
406  AkMemPoolId poolId,
407  void* pAddress
408  );
409 
410 //@}
411 
412 }
413 
414 }
void(* AkMemDebugMalloc)(AkMemPoolId poolId, size_t uSize, void *pAddress, char const *pszFile, AkUInt32 uLine)
Definition: AkModule.h:85
AKSOUNDENGINE_API AKRESULT AkMemDebugToolInit()
Audiokinetic namespace.
AkMemTermForThread pfTermForThread
(Optional) Thread-specific allocator termination hook.
Definition: AkModule.h:159
void(* AkMemInitForThread)()
Definition: AkModule.h:38
@ AkSpanCount_Medium
Definition: AkModule.h:144
AKSOUNDENGINE_API void AkMemDebugToolMalloc(AkMemPoolId poolId, size_t uSize, void *pAddress, char const *pszFile, AkUInt32 uLine)
AkUInt32 uMaxThreadLocalHeapAllocSize
All memory allocations of sizes larger than this value will go to a global heap shared across all thr...
Definition: AkModule.h:187
AkMemInitForThread pfInitForThread
(Optional) Thread-specific allocator initialization hook.
Definition: AkModule.h:158
AkMemFree pfFree
(Optional) Memory allocation hook.
Definition: AkModule.h:165
AkMemMalign pfMalign
(Optional) Memory allocation hook.
Definition: AkModule.h:162
AKSOUNDENGINE_API AKRESULT Init(AkMemSettings *in_pSettings)
AkSpanCount
Definition: AkModule.h:139
AKSOUNDENGINE_API void AkCrtAllocatorInitForThread()
AkSpanCount uVMSpanCount
Virtual memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge....
Definition: AkModule.h:201
#define AK_EXTERNAPIFUNC(_type, _name)
AkMemRealloc pfRealloc
(Optional) Memory allocation hook.
Definition: AkModule.h:163
AkMemFreeVM pfFreeVM
Virtual page allocation hook.
Definition: AkModule.h:180
AKRESULT
Standard function call result.
Definition: AkTypes.h:131
void *(* AkMemRealloc)(AkMemPoolId poolId, void *pAddress, size_t uSize)
Definition: AkModule.h:58
AKSOUNDENGINE_API void AkMemDebugToolFree(AkMemPoolId poolId, void *pAddress)
@ AkSpanCount_Huge
Definition: AkModule.h:147
AkInt32 AkMemPoolId
Memory pool ID.
Definition: AkTypes.h:62
AkMemDebugRealloc pfDebugRealloc
(Optional) Memory allocation debugging hook. Used for tracking calls to pfRealloc.
Definition: AkModule.h:194
void(* AkMemDebugRealloc)(AkMemPoolId poolId, void *pOldAddress, size_t uSize, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
Definition: AkModule.h:102
void *(* AkMemAllocVM)(size_t size, size_t *extra)
Definition: AkModule.h:126
AkMemDebugReallocAligned pfDebugReallocAligned
(Optional) Memory allocation debugging hook. Used for tracking calls to pfReallocAligned.
Definition: AkModule.h:195
void *(* AkMemReallocAligned)(AkMemPoolId poolId, void *pAddress, size_t uSize, AkUInt32 uAlignment)
Definition: AkModule.h:65
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...
Definition: AkModule.h:160
AKSOUNDENGINE_API void AkMemDebugToolMalign(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment, void *pAddress, char const *pszFile, AkUInt32 uLine)
void *(* AkMemMalloc)(AkMemPoolId poolId, size_t uSize)
Definition: AkModule.h:47
AKSOUNDENGINE_API void AkCrtAllocatorFree(AkMemPoolId poolId, void *pAddress)
AkMemReallocAligned pfReallocAligned
(Optional) Memory allocation hook.
Definition: AkModule.h:164
AkMemFreeVM pfFreeDevice
Device page allocation hook.
Definition: AkModule.h:182
size_t(* AkMemTotalReservedMemorySize)()
Definition: AkModule.h:77
AkMemAllocVM pfAllocVM
Virtual page allocation hook.
Definition: AkModule.h:179
AKSOUNDENGINE_API void * AkCrtAllocatorRealloc(AkMemPoolId poolId, void *pAddress, size_t uSize)
void(* AkMemTermForThread)()
Definition: AkModule.h:41
AkUInt64 uMemAllocationSizeLimit
When non-zero, limits the total amount of virtual and device memory allocated by AK::MemoryMgr.
Definition: AkModule.h:172
void(* AkMemDebugReallocAligned)(AkMemPoolId poolId, void *pOldAddress, size_t uSize, AkUInt32 uAlignment, void *pNewAddress, char const *pszFile, AkUInt32 uLine)
Definition: AkModule.h:111
AKSOUNDENGINE_API size_t AkCrtAllocatorSizeOfMemory(AkMemPoolId poolID, void *pAddress)
void(* AkMemTrimForThread)()
Definition: AkModule.h:44
AK::TempAlloc::InitSettings tempAllocSettings[AK::TempAlloc::Type_NUM]
Configuration of behavior for the temporary-memory pools. For more information, see Tuning "Temp Allo...
Definition: AkModule.h:174
void(* AkMemFree)(AkMemPoolId poolId, void *pAddress)
Definition: AkModule.h:72
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.
bool bEnableSeparateDeviceHeap
Enable use of device memory heap for all allocations (on applicable platforms).
Definition: AkModule.h:173
void *(* AkMemMalign)(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment)
Definition: AkModule.h:52
AkUInt32 uMemoryDebugLevel
Default 0 disabled. 1 debug enabled. 2 stomp allocator enabled. 3 stomp allocator and debug enabled....
Definition: AkModule.h:197
AkSpanCount uDeviceSpanCount
Device memory span count for each map operation in rpmalloc. Defaults to AkSpanCount_Huge....
Definition: AkModule.h:202
AKSOUNDENGINE_API void * AkCrtAllocatorMalloc(AkMemPoolId poolId, size_t uSize)
#define AKSOUNDENGINE_CALL
Calling convention for the Wwise API.
Definition: AkTypes.h:105
AkUInt32 uDevicePageSize
Device memory page size. Defaults to 0 which means auto-detect.
Definition: AkModule.h:184
AkMemTotalReservedMemorySize pfTotalReservedMemorySize
(Optional) Memory allocation statistics hook.
Definition: AkModule.h:166
AkMemMalloc pfMalloc
(Optional) Memory allocation hook.
Definition: AkModule.h:161
@ AkSpanCount_Small
Definition: AkModule.h:141
AKSOUNDENGINE_API void AkCrtAllocatorTermForThread()
Initialization settings for temporary-memory pools. Separate settings are specified for each temporar...
Definition: AkMemoryMgr.h:343
uint64_t AkUInt64
Unsigned 64-bit integer.
void(* AkMemFreeVM)(void *address, size_t size, size_t extra, size_t release)
Definition: AkModule.h:131
AkMemDebugMalloc pfDebugMalloc
(Optional) Memory allocation debugging hook. Used for tracking calls to pfMalloc.
Definition: AkModule.h:192
@ AkSpanCount_END
Definition: AkModule.h:149
uint32_t AkUInt32
Unsigned 32-bit integer.
size_t(* AkMemSizeOfMemory)(AkMemPoolId poolId, void *pAddress)
Definition: AkModule.h:80
AkUInt32 uVMPageSize
Virtual memory page size. Defaults to 0 which means auto-detect.
Definition: AkModule.h:183
void(* AkMemDebugMalign)(AkMemPoolId poolId, size_t uSize, AkUInt32 uAlignment, void *pAddress, char const *pszFile, AkUInt32 uLine)
Definition: AkModule.h:93
AKSOUNDENGINE_API size_t AkCrtAllocatorTotalReservedMemorySize()
AKSOUNDENGINE_API void AkCrtAllocatorTrimForThread()
void(* AkMemDebugFree)(AkMemPoolId poolId, void *pAddress)
Definition: AkModule.h:121
AkMemDebugFree pfDebugFree
(Optional) Memory allocation debugging hook. Used for tracking calls to pfFree.
Definition: AkModule.h:196
AkMemSizeOfMemory pfSizeOfMemory
(Optional) Memory allocation statistics hook.
Definition: AkModule.h:167
AkMemDebugMalign pfDebugMalign
(Optional) Memory allocation debugging hook. Used for tracking calls to pfMalign.
Definition: AkModule.h:193
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)
AkMemAllocVM pfAllocDevice
Device page allocation hook.
Definition: AkModule.h:181

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