Version
menu_open
link
Wwise SDK 2019.1.11
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 #ifndef AK_OPTIMIZED
38 
39 #define AK_MAX_MEM_POOL_NAME_SIZE 64
40 
41 /// Set the debug name for a pool. This is the name shown in the Memory tab of the Advanced Profiler.
42 #define AK_SETPOOLNAME( _poolid, _name ) \
43  if( AK_INVALID_POOL_ID != _poolid ) \
44  { \
45  AK::MemoryMgr::SetPoolName( _poolid, _name ); \
46  }
47 
48 // #define AK_MEMDEBUG
49 
50 #ifdef MSTC_SYSTEMATIC_MEMORY_STRESS
51 #define AK_MEMDEBUG
52 #endif
53 
54 #else
55 #define AK_SETPOOLNAME(_poolid,_name)
56 #endif
57 
58 
59 namespace AK
60 {
61  /// Memory Manager namespace.
62  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
63  /// \sa
64  /// - \ref memorymanager
65  namespace MemoryMgr
66  {
67  /// Memory pool statistics.
68  /// \remarks These statistics are not collected in the Release configuration of
69  /// the default memory manager implementation.
70  /// \sa
71  /// - AK::MemoryMgr::GetPoolStats()
72  /// - \ref memorymanager
73  struct PoolStats
74  {
75  // Current state
76  AkUInt32 uReserved; ///< Reserved memory (in bytes)
77  AkUInt32 uUsed; ///< Used memory (in bytes)
78  AkUInt32 uMaxFreeBlock; ///< Size of biggest free block (in bytes)
79 
80  // Statistics
81  AkUInt32 uAllocs; ///< Number of Alloc calls since initialization
82  AkUInt32 uFrees; ///< Number of Free calls since initialization
83  AkUInt32 uPeakUsed; ///< Peak used memory (in bytes)
84  };
85 
86  /// Memory pool current state.
87  /// \sa
88  /// - AK::MemoryMgr::GetPoolMemoryUsed()
89  /// - \ref memorymanager
90  struct PoolMemInfo
91  {
92  // Current state
93  AkUInt32 uReserved; ///< Reserved memory (in bytes)
94  AkUInt32 uUsed; ///< Used memory (in bytes)
95  };
96 
97 
98  /// Memory management debug tools. When specified in Init, each memory allocation will have a extra tag that can be verified periodically.
99  /// Enabling this will use a lot of CPU and additional memory. This should not be enabled unless required by Audiokinetic's support. These are enabled in Debug configuration only.
101  {
102  CheckOverwriteAtFree = 1, ///< Performs a for buffer overflow when an allocation is freed.
103  CheckOverwritePerFrame = 2, ///< Performs a check for buffer overflow once per audio frame
104  CheckOverwritePerVoice = 4, ///< Performs a check for buffer overflow once per audio voice
105  };
106 
107  /// Query whether the Memory Manager has been sucessfully initialized.
108  /// \warning This function is not thread-safe. It should not be called at the same time as MemoryMgr::Init or MemoryMgr::Term.
109  /// \return True if the Memory Manager is initialized, False otherwise
110  /// \sa
111  /// - AK::MemoryMgr::Init()
112  /// - \ref memorymanager
113  AK_EXTERNAPIFUNC( bool, IsInitialized )();
114 
115  /// Terminate the Memory Manager.
116  /// \warning This function is not thread-safe.
117  /// \sa
118  /// - \ref memorymanager
119  AK_EXTERNAPIFUNC( void, Term )();
120 
121  ////////////////////////////////////////////////////////////////////////
122  /// @name Memory Pools
123  //@{
124 
125  /// Create a new memory pool.
126  /// \return The ID of the created memory pool, or AK_INVALID_POOL_ID if creation failed
127  /// \aktip
128  /// Refer to \ref memorymanager_pools for information about pool resource overhead.
129  /// \endaktip
130  /// \sa
131  /// - \ref memorymanager
132  AK_EXTERNAPIFUNC( AkMemPoolId, CreatePool )(
133  void * in_pMemAddress, ///< Memory address of the pool, or NULL if it should be allocated
134  AkUInt32 in_uMemSize, ///< Size of the pool (in bytes)
135  AkUInt32 in_uBlockSize, ///< Size of a block (in bytes)
136  AkUInt32 in_eAttributes, ///< Memory pool attributes: use values of \ref AkMemPoolAttributes
137  AkUInt32 in_uBlockAlign = 0 ///< Alignment of memory blocks.
138  ///< Some plug-ins and specific processors may require specific data alignment.
139  ///< When allocating space for sound bank data, we recommend using AK_BANK_PLATFORM_DATA_ALIGNMENT.
140  );
141 
142 #ifdef AK_SUPPORT_WCHAR
143  /// Set the name of a memory pool.
144  /// \return AK_Success if successful
145  /// \sa
146  /// - \ref memorymanager
147  AK_EXTERNAPIFUNC( AKRESULT, SetPoolName )(
148  AkMemPoolId in_poolId, ///< ID of memory pool
149  const wchar_t* in_pszPoolName ///< Pointer to unicode name string
150  );
151 #endif //AK_SUPPORT_WCHAR
152 
153  /// Set the name of a memory pool.
154  /// \return AK_Success if successful
155  /// \sa
156  /// - \ref memorymanager
157  AK_EXTERNAPIFUNC( AKRESULT, SetPoolName )(
158  AkMemPoolId in_poolId, ///< ID of memory pool
159  const char* in_pszPoolName ///< Pointer to name string
160  );
161 
162  /// Get the name of a memory pool.
163  /// \return A pointer to the name of the memory pool (NULL if the operation failed)
164  /// \sa
165  /// - \ref memorymanager
166  AK_EXTERNAPIFUNC( AkOSChar*, GetPoolName )(
167  AkMemPoolId in_poolId ///< ID of memory pool
168  );
169 
170  /// Enables or disables error notifications posted by a memory pool.
171  /// The notifications are enabled by default when creating a pool.
172  /// They are always disabled in the Release build.
173  /// \return AK_Success if the pool exists
174  /// \sa
175  /// - \ref memorymanager
176  AK_EXTERNAPIFUNC( AKRESULT, SetMonitoring )(
177  AkMemPoolId in_poolId, ///< ID of memory pool
178  bool in_bDoMonitor ///< Enables error monitoring (has no effect in Release build)
179  );
180 
181  /// Destroy a memory pool.
182  /// \return AK_Success if successful
183  /// \sa
184  /// - \ref memorymanager
185  AK_EXTERNAPIFUNC( AKRESULT, DestroyPool )(
186  AkMemPoolId in_poolId ///< ID of memory pool
187  );
188 
189  /// Get a memory pool's statistics.
190  /// \sa
191  /// - AK::MemoryMgr::PoolStats
192  /// - \ref memorymanager
193  AK_EXTERNAPIFUNC( AKRESULT, GetPoolStats )(
194  AkMemPoolId in_poolId, ///< ID of memory pool
195  PoolStats& out_stats ///< Returned statistics structure
196  );
197 
198  /// Get a memory pool current used size.
199  /// Mostly used by the memory threshold features.
200  /// If this function cannot be implemented if your memory manager, at least set the member uUsed to 0, that
201  /// will disable the memory threshold feature.
202  /// \sa
203  /// - AK::MemoryMgr::PoolMemInfo
204  /// - \ref memorymanager
205  AK_EXTERNAPIFUNC( void, GetPoolMemoryUsed )(
206  AkMemPoolId in_poolId, ///< ID of memory pool
207  PoolMemInfo& out_memInfo ///< Returned statistics structure
208  );
209 
210  /// Get the current number of memory pools.
211  /// \return The current number of memory pools
212  /// \sa
213  /// - \ref memorymanager
214  AK_EXTERNAPIFUNC( AkInt32, GetNumPools )();
215 
216  /// Get the maximum number of memory pools.
217  /// \return The maximum number of memory pools
218  /// \sa
219  /// - \ref memorymanager
220  AK_EXTERNAPIFUNC( AkInt32, GetMaxPools )();
221 
222  /// Test the validity of a pool ID.
223  /// This is used to verify the validity of a memory pool ID.
224  /// \return AK_Success if the pool exists, AK_InvalidID otherwise
225  /// \sa
226  /// - \ref memorymanager
227  AK_EXTERNAPIFUNC( AKRESULT, CheckPoolId )(
228  AkMemPoolId in_poolId ///< ID of memory pool to test
229  );
230 
231  /// Get pool attributes.
232  /// \return The memory pool's attributes.
233  /// \sa
234  /// - \ref memorymanager
235  AK_EXTERNAPIFUNC( AkMemPoolAttributes, GetPoolAttributes )(
236  AkMemPoolId in_poolId ///< ID of memory pool
237  );
238 
239  //@}
240 
241  ////////////////////////////////////////////////////////////////////////
242  /// @name Memory Allocation
243  //@{
244 
245 #if defined (AK_MEMDEBUG)
246  /// Allocate memory from a pool: debug version.
247  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
248  /// \sa
249  /// - \ref memorymanager
250  AK_EXTERNAPIFUNC( void *, dMalloc )(
251  AkMemPoolId in_poolId, ///< ID of the memory pool
252  size_t in_uSize, ///< Number of bytes to allocate
253  const char *in_pszFile, ///< Debug file name
254  AkUInt32 in_uLine ///< Debug line number
255  );
256 #endif
257  /// Allocate memory from a pool.
258  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
259  /// \sa
260  /// - \ref memorymanager
261  AK_EXTERNAPIFUNC( void *, Malloc )(
262  AkMemPoolId in_poolId, ///< ID of the memory pool
263  size_t in_uSize ///< Number of bytes to allocate
264  );
265 
266  /// Reallocate memory from a pool.
267  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
268  /// \sa
269  /// - \ref memorymanager
270  AK_EXTERNAPIFUNC(void *, Realloc)(
271  AkMemPoolId in_poolId, ///< ID of the memory pool
272  void *in_pAlloc, ///< Pointer to the start of the allocated memory
273  size_t in_uSize ///< Number of bytes to allocate
274  );
275 
276  /// Free memory from a pool.
277  /// \return AK_Success if successful
278  /// \sa
279  /// - \ref memorymanager
280  AK_EXTERNAPIFUNC( AKRESULT, Free )(
281  AkMemPoolId in_poolId, ///< ID of the memory pool
282  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc
283  );
284 
285 #if defined (AK_MEMDEBUG)
286  /// Allocate memory from a pool, overriding the pool's default memory alignment. Needs to be used
287  /// in conjunction with AK::MemoryMgr::Falign. debug version.
288  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
289  /// \sa
290  /// - \ref memorymanager
291  AK_EXTERNAPIFUNC( void *, dMalign )(
292  AkMemPoolId in_poolId, ///< ID of the memory pool
293  size_t in_uSize, ///< Number of bytes to allocate
294  AkUInt32 in_uAlignment, ///< Alignment (in bytes)
295  const char* in_pszFile, ///< Debug file name
296  AkUInt32 in_uLine ///< Debug line number
297  );
298 #endif
299 
300  /// Allocate memory from a pool, overriding the pool's default memory alignment. Needs to be used
301  /// in conjunction with AK::MemoryMgr::Falign.
302  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
303  /// \sa
304  /// - \ref memorymanager
305  AK_EXTERNAPIFUNC( void *, Malign )(
306  AkMemPoolId in_poolId, ///< ID of the memory pool
307  size_t in_uSize, ///< Number of bytes to allocate
308  AkUInt32 in_uAlignment ///< Alignment (in bytes)
309  );
310 
311  /// Free memory from a pool, overriding the pool's default memory alignment. Needs to be used in
312  /// conjunction with AK::MemoryMgr::Malign.
313  ///
314  /// \return AK_Success if successful
315  /// \sa
316  /// - \ref memorymanager
317  AK_EXTERNAPIFUNC( AKRESULT, Falign )(
318  AkMemPoolId in_poolId, ///< ID of the memory pool
319  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malign
320  );
321 
322  //@}
323 
324  ////////////////////////////////////////////////////////////////////////
325  /// @name Fixed-Size Blocks Memory Allocation Mode
326  //@{
327 
328  /// Get a block from a Fixed-Size Block type pool. To be used with pools created with AkFixedSizeBlocksMode
329  /// block management type, along with any of the block allocation types.
330  /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory)
331  /// The size of the memory block is always in_uBlockSize, specified in AK::MemoryMgr::CreatePool.
332  /// \warning This method is not thread-safe. Fixed-Size Block pool access must be protected.
333  /// \sa
334  /// - AK::MemoryMgr::CreatePool
335  /// - AkMemPoolAttributes
336  /// - \ref memorymanager
337  AK_EXTERNAPIFUNC( void *, GetBlock )(
338  AkMemPoolId in_poolId ///< ID of the memory pool
339  );
340 
341  /// Free memory from a Fixed-Size Block type pool.
342  /// \return AK_Success if successful
343  /// \warning This method is not thread-safe. Fixed-Size Block pool access must be protected.
344  /// \sa
345  /// - \ref memorymanager
346  AK_EXTERNAPIFUNC( AKRESULT, ReleaseBlock )(
347  AkMemPoolId in_poolId, ///< ID of the memory pool
348  void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc
349  );
350 
351  /// Get block size of blocks obtained with GetBlock() for a given memory pool.
352  /// The block size is fixed and set when creating a pool with AkFixedSizeBlocksMode.
353  /// \return Block size
354  /// \sa
355  /// - AK::MemoryMgr::CreatePool
356  /// - AK::MemoryMgr::GetBlock
357  /// - \ref memorymanager
358  AK_EXTERNAPIFUNC( AkUInt32, GetBlockSize )(
359  AkMemPoolId in_poolId ///< ID of the memory pool
360  );
361 
362  /// Called to start profiling memory usage for one thread (the calling thread).
363  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
364  AK_EXTERNAPIFUNC( void, StartProfileThreadUsage) (
365  AkMemPoolId in_PoolId ///< Pool to profile
366  );
367 
368  /// Called to stop profiling memory usage for the current thread.
369  /// \return The amount of memory allocated by this thread since \ref StartProfileThreadUsage was called.
370  /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage.
371  AK_EXTERNAPIFUNC( AkUInt32, StopProfileThreadUsage ) (
372  AkMemPoolId in_PoolId ///< Pool to profile
373  );
374 
375 
376  /// Debugging method that verifies if buffer overflow occurred in a specific pool.
377  /// Called at various moments depending on the DebugFlags set in AkMemSettings.
378  /// In the default implementation it is not called in Release otherwise will assert if overrun found.
379  /// Implementation is not mendatory if the MemoryMgr is overriden.
380  AK_EXTERNAPIFUNC(void, CheckForOverwrite) (
381  AkUInt32 in_uPoolID
382  );
383 
384 #if defined (AK_MEMDEBUG)
385  /// Debugging method that dumps a snapshot list of actual memory allocations to a file.
386  /// The list contains the size allocated and the source file and line number where the memory allocation was done.
387  AK_EXTERNAPIFUNC(void, DumpToFile) (const char* strFileName = "AkMemDump.txt");
388 #endif
389  //@}
390  }
391 }
392 
393 #endif // _AKMEMORYMGR_H_
AKSOUNDENGINE_API AkOSChar * GetPoolName(AkMemPoolId in_poolId)
AkUInt32 uUsed
Used memory (in bytes)
Definition: AkMemoryMgr.h:94
Audiokinetic namespace.
AKSOUNDENGINE_API AkUInt32 StopProfileThreadUsage(AkMemPoolId in_PoolId)
AKSOUNDENGINE_API AKRESULT Falign(AkMemPoolId in_poolId, void *in_pMemAddress)
AKSOUNDENGINE_API AKRESULT SetPoolName(AkMemPoolId in_poolId, const char *in_pszPoolName)
AKSOUNDENGINE_API AkMemPoolId CreatePool(void *in_pMemAddress, AkUInt32 in_uMemSize, AkUInt32 in_uBlockSize, AkUInt32 in_eAttributes, AkUInt32 in_uBlockAlign=0)
AKSOUNDENGINE_API AKRESULT CheckPoolId(AkMemPoolId in_poolId)
@ CheckOverwriteAtFree
Performs a for buffer overflow when an allocation is freed.
Definition: AkMemoryMgr.h:102
AKSOUNDENGINE_API void * Malloc(AkMemPoolId in_poolId, size_t in_uSize)
AKSOUNDENGINE_API AKRESULT Free(AkMemPoolId in_poolId, void *in_pMemAddress)
AKSOUNDENGINE_API AKRESULT GetPoolStats(AkMemPoolId in_poolId, PoolStats &out_stats)
AKSOUNDENGINE_API void Term()
AKSOUNDENGINE_API void GetPoolMemoryUsed(AkMemPoolId in_poolId, PoolMemInfo &out_memInfo)
AKSOUNDENGINE_API void CheckForOverwrite(AkUInt32 in_uPoolID)
AKSOUNDENGINE_API AKRESULT SetMonitoring(AkMemPoolId in_poolId, bool in_bDoMonitor)
AKSOUNDENGINE_API void * Malign(AkMemPoolId in_poolId, size_t in_uSize, AkUInt32 in_uAlignment)
AkUInt32 uReserved
Reserved memory (in bytes)
Definition: AkMemoryMgr.h:93
AKSOUNDENGINE_API AkMemPoolAttributes GetPoolAttributes(AkMemPoolId in_poolId)
AkUInt32 uFrees
Number of Free calls since initialization.
Definition: AkMemoryMgr.h:82
AkUInt32 uAllocs
Number of Alloc calls since initialization.
Definition: AkMemoryMgr.h:81
AKSOUNDENGINE_API AkUInt32 GetBlockSize(AkMemPoolId in_poolId)
AKSOUNDENGINE_API void * Realloc(AkMemPoolId in_poolId, void *in_pAlloc, size_t in_uSize)
AkUInt32 uMaxFreeBlock
Size of biggest free block (in bytes)
Definition: AkMemoryMgr.h:78
AKSOUNDENGINE_API AkInt32 GetNumPools()
AKSOUNDENGINE_API void * GetBlock(AkMemPoolId in_poolId)
@ CheckOverwritePerFrame
Performs a check for buffer overflow once per audio frame.
Definition: AkMemoryMgr.h:103
AkUInt32 uPeakUsed
Peak used memory (in bytes)
Definition: AkMemoryMgr.h:83
AkUInt32 uReserved
Reserved memory (in bytes)
Definition: AkMemoryMgr.h:76
AKSOUNDENGINE_API bool IsInitialized()
AKSOUNDENGINE_API AKRESULT DestroyPool(AkMemPoolId in_poolId)
AkUInt32 uUsed
Used memory (in bytes)
Definition: AkMemoryMgr.h:77
AKSOUNDENGINE_API void StartProfileThreadUsage(AkMemPoolId in_PoolId)
AKSOUNDENGINE_API AKRESULT ReleaseBlock(AkMemPoolId in_poolId, void *in_pMemAddress)
@ CheckOverwritePerVoice
Performs a check for buffer overflow once per audio voice
Definition: AkMemoryMgr.h:104
AKSOUNDENGINE_API AkInt32 GetMaxPools()

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