00001 /******************************************************************************* 00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology 00003 released in source code form as part of the SDK installer package. 00004 00005 Commercial License Usage 00006 00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology 00008 may use this file in accordance with the end user license agreement provided 00009 with the software or, alternatively, in accordance with the terms contained in a 00010 written agreement between you and Audiokinetic Inc. 00011 00012 Apache License Usage 00013 00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 00015 "Apache License"); you may not use this file except in compliance with the 00016 Apache License. You may obtain a copy of the Apache License at 00017 http://www.apache.org/licenses/LICENSE-2.0. 00018 00019 Unless required by applicable law or agreed to in writing, software distributed 00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES 00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for 00022 the specific language governing permissions and limitations under the License. 00023 00024 Version: <VERSION> Build: <BUILDNUMBER> 00025 Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc. 00026 *******************************************************************************/ 00027 00028 /// \file 00029 /// Memory Manager namespace. 00030 00031 #ifndef _AKMEMORYMGR_H_ 00032 #define _AKMEMORYMGR_H_ 00033 00034 #include <AK/SoundEngine/Common/AkTypes.h> 00035 #include <AK/SoundEngine/Common/AkSoundEngineExport.h> 00036 00037 #ifndef AK_OPTIMIZED 00038 00039 #define AK_MAX_MEM_POOL_NAME_SIZE 64 00040 00041 /// Set the debug name for a pool. This is the name shown in the Memory tab of the Advanced Profiler. 00042 #define AK_SETPOOLNAME( _poolid, _name ) \ 00043 if( AK_INVALID_POOL_ID != _poolid ) \ 00044 { \ 00045 AK::MemoryMgr::SetPoolName( _poolid, _name ); \ 00046 } 00047 00048 //#define AK_MEMDEBUG 00049 00050 #else 00051 #define AK_SETPOOLNAME(_poolid,_name) 00052 #endif 00053 00054 00055 namespace AK 00056 { 00057 /// Memory Manager namespace. 00058 /// \remarks The functions in this namespace are thread-safe, unless stated otherwise. 00059 /// \sa 00060 /// - \ref memorymanager 00061 namespace MemoryMgr 00062 { 00063 /// Memory pool statistics. 00064 /// \remarks These statistics are not collected in the Release configuration of 00065 /// the default memory manager implementation. 00066 /// \sa 00067 /// - AK::MemoryMgr::GetPoolStats() 00068 /// - \ref memorymanager 00069 struct PoolStats 00070 { 00071 // Current state 00072 AkUInt32 uReserved; ///< Reserved memory (in bytes) 00073 AkUInt32 uUsed; ///< Used memory (in bytes) 00074 AkUInt32 uMaxFreeBlock; ///< Size of biggest free block (in bytes) 00075 00076 // Statistics 00077 AkUInt32 uAllocs; ///< Number of Alloc calls since initialization 00078 AkUInt32 uFrees; ///< Number of Free calls since initialization 00079 AkUInt32 uPeakUsed; ///< Peak used memory (in bytes) 00080 }; 00081 00082 /// Memory pool current state. 00083 /// \sa 00084 /// - AK::MemoryMgr::GetPoolMemoryUsed() 00085 /// - \ref memorymanager 00086 struct PoolMemInfo 00087 { 00088 // Current state 00089 AkUInt32 uReserved; ///< Reserved memory (in bytes) 00090 AkUInt32 uUsed; ///< Used memory (in bytes) 00091 }; 00092 00093 00094 /// Memory management debug tools. When specified in Init, each memory allocation will have a extra tag that can be verified periodically. 00095 /// 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. 00096 enum DebugFlags 00097 { 00098 CheckOverwriteAtFree = 1, ///< Performs a for buffer overflow when an allocation is freed. 00099 CheckOverwritePerFrame = 2, ///< Performs a check for buffer overflow once per audio frame 00100 CheckOverwritePerVoice = 4, ///< Performs a check for buffer overflow once per audio voice 00101 }; 00102 00103 /// Query whether the Memory Manager has been sucessfully initialized. 00104 /// \warning This function is not thread-safe. It should not be called at the same time as MemoryMgr::Init or MemoryMgr::Term. 00105 /// \return True if the Memory Manager is initialized, False otherwise 00106 /// \sa 00107 /// - AK::MemoryMgr::Init() 00108 /// - \ref memorymanager 00109 AK_EXTERNAPIFUNC( bool, IsInitialized )(); 00110 00111 /// Terminate the Memory Manager. 00112 /// \warning This function is not thread-safe. 00113 /// \sa 00114 /// - \ref memorymanager 00115 AK_EXTERNAPIFUNC( void, Term )(); 00116 00117 //////////////////////////////////////////////////////////////////////// 00118 /// @name Memory Pools 00119 //@{ 00120 00121 /// Create a new memory pool. 00122 /// \return The ID of the created memory pool, or AK_INVALID_POOL_ID if creation failed 00123 /// \aktip 00124 /// Refer to \ref memorymanager_pools for information about pool resource overhead. 00125 /// \endaktip 00126 /// \sa 00127 /// - \ref memorymanager 00128 AK_EXTERNAPIFUNC( AkMemPoolId, CreatePool )( 00129 void * in_pMemAddress, ///< Memory address of the pool, or NULL if it should be allocated 00130 AkUInt32 in_uMemSize, ///< Size of the pool (in bytes) 00131 AkUInt32 in_uBlockSize, ///< Size of a block (in bytes) 00132 AkUInt32 in_eAttributes, ///< Memory pool attributes: use values of \ref AkMemPoolAttributes 00133 AkUInt32 in_uBlockAlign = 0 ///< Alignment of memory blocks 00134 ); 00135 00136 #ifdef AK_SUPPORT_WCHAR 00137 /// Set the name of a memory pool. 00138 /// \return AK_Success if successful 00139 /// \sa 00140 /// - \ref memorymanager 00141 AK_EXTERNAPIFUNC( AKRESULT, SetPoolName )( 00142 AkMemPoolId in_poolId, ///< ID of memory pool 00143 const wchar_t* in_pszPoolName ///< Pointer to unicode name string 00144 ); 00145 #endif //AK_SUPPORT_WCHAR 00146 00147 /// Set the name of a memory pool. 00148 /// \return AK_Success if successful 00149 /// \sa 00150 /// - \ref memorymanager 00151 AK_EXTERNAPIFUNC( AKRESULT, SetPoolName )( 00152 AkMemPoolId in_poolId, ///< ID of memory pool 00153 const char* in_pszPoolName ///< Pointer to name string 00154 ); 00155 00156 /// Get the name of a memory pool. 00157 /// \return A pointer to the name of the memory pool (NULL if the operation failed) 00158 /// \sa 00159 /// - \ref memorymanager 00160 AK_EXTERNAPIFUNC( AkOSChar*, GetPoolName )( 00161 AkMemPoolId in_poolId ///< ID of memory pool 00162 ); 00163 00164 /// Enables or disables error notifications posted by a memory pool. 00165 /// The notifications are enabled by default when creating a pool. 00166 /// They are always disabled in the Release build. 00167 /// \return AK_Success if the pool exists 00168 /// \sa 00169 /// - \ref memorymanager 00170 AK_EXTERNAPIFUNC( AKRESULT, SetMonitoring )( 00171 AkMemPoolId in_poolId, ///< ID of memory pool 00172 bool in_bDoMonitor ///< Enables error monitoring (has no effect in Release build) 00173 ); 00174 00175 /// Destroy a memory pool. 00176 /// \return AK_Success if successful 00177 /// \sa 00178 /// - \ref memorymanager 00179 AK_EXTERNAPIFUNC( AKRESULT, DestroyPool )( 00180 AkMemPoolId in_poolId ///< ID of memory pool 00181 ); 00182 00183 /// Get a memory pool's statistics. 00184 /// \sa 00185 /// - AK::MemoryMgr::PoolStats 00186 /// - \ref memorymanager 00187 AK_EXTERNAPIFUNC( AKRESULT, GetPoolStats )( 00188 AkMemPoolId in_poolId, ///< ID of memory pool 00189 PoolStats& out_stats ///< Returned statistics structure 00190 ); 00191 00192 /// Get a memory pool current used size. 00193 /// Mostly used by the memory threshold features. 00194 /// If this function cannot be implemented if your memory manager, at least set the member uUsed to 0, that 00195 /// will disable the memory threshold feature. 00196 /// \sa 00197 /// - AK::MemoryMgr::PoolMemInfo 00198 /// - \ref memorymanager 00199 AK_EXTERNAPIFUNC( void, GetPoolMemoryUsed )( 00200 AkMemPoolId in_poolId, ///< ID of memory pool 00201 PoolMemInfo& out_memInfo ///< Returned statistics structure 00202 ); 00203 00204 /// Get the current number of memory pools. 00205 /// \return The current number of memory pools 00206 /// \sa 00207 /// - \ref memorymanager 00208 AK_EXTERNAPIFUNC( AkInt32, GetNumPools )(); 00209 00210 /// Get the maximum number of memory pools. 00211 /// \return The maximum number of memory pools 00212 /// \sa 00213 /// - \ref memorymanager 00214 AK_EXTERNAPIFUNC( AkInt32, GetMaxPools )(); 00215 00216 /// Test the validity of a pool ID. 00217 /// This is used to verify the validity of a memory pool ID. 00218 /// \return AK_Success if the pool exists, AK_InvalidID otherwise 00219 /// \sa 00220 /// - \ref memorymanager 00221 AK_EXTERNAPIFUNC( AKRESULT, CheckPoolId )( 00222 AkMemPoolId in_poolId ///< ID of memory pool to test 00223 ); 00224 00225 /// Get pool attributes. 00226 /// \return The memory pool's attributes. 00227 /// \sa 00228 /// - \ref memorymanager 00229 AK_EXTERNAPIFUNC( AkMemPoolAttributes, GetPoolAttributes )( 00230 AkMemPoolId in_poolId ///< ID of memory pool 00231 ); 00232 00233 //@} 00234 00235 //////////////////////////////////////////////////////////////////////// 00236 /// @name Memory Allocation 00237 //@{ 00238 00239 #if defined (AK_MEMDEBUG) 00240 /// Allocate memory from a pool: debug version. 00241 /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory) 00242 /// \sa 00243 /// - \ref memorymanager 00244 AK_EXTERNAPIFUNC( void *, dMalloc )( 00245 AkMemPoolId in_poolId, ///< ID of the memory pool 00246 size_t in_uSize, ///< Number of bytes to allocate 00247 const char *in_pszFile, ///< Debug file name 00248 AkUInt32 in_uLine ///< Debug line number 00249 ); 00250 #endif 00251 /// Allocate memory from a pool. 00252 /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory) 00253 /// \sa 00254 /// - \ref memorymanager 00255 AK_EXTERNAPIFUNC( void *, Malloc )( 00256 AkMemPoolId in_poolId, ///< ID of the memory pool 00257 size_t in_uSize ///< Number of bytes to allocate 00258 ); 00259 00260 /// Free memory from a pool. 00261 /// \return AK_Success if successful 00262 /// \sa 00263 /// - \ref memorymanager 00264 AK_EXTERNAPIFUNC( AKRESULT, Free )( 00265 AkMemPoolId in_poolId, ///< ID of the memory pool 00266 void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc 00267 ); 00268 00269 #if defined (AK_MEMDEBUG) 00270 /// Allocate memory from a pool, overriding the pool's default memory alignment. Needs to be used 00271 /// in conjunction with AK::MemoryMgr::Falign. debug version. 00272 /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory) 00273 /// \sa 00274 /// - \ref memorymanager 00275 AK_EXTERNAPIFUNC( void *, dMalign )( 00276 AkMemPoolId in_poolId, ///< ID of the memory pool 00277 size_t in_uSize, ///< Number of bytes to allocate 00278 AkUInt32 in_uAlignment, ///< Alignment (in bytes) 00279 const char* in_pszFile, ///< Debug file name 00280 AkUInt32 in_uLine ///< Debug line number 00281 ); 00282 #endif 00283 00284 /// Allocate memory from a pool, overriding the pool's default memory alignment. Needs to be used 00285 /// in conjunction with AK::MemoryMgr::Falign. 00286 /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory) 00287 /// \sa 00288 /// - \ref memorymanager 00289 AK_EXTERNAPIFUNC( void *, Malign )( 00290 AkMemPoolId in_poolId, ///< ID of the memory pool 00291 size_t in_uSize, ///< Number of bytes to allocate 00292 AkUInt32 in_uAlignment ///< Alignment (in bytes) 00293 ); 00294 00295 /// Free memory from a pool, overriding the pool's default memory alignment. Needs to be used in 00296 /// conjunction with AK::MemoryMgr::Malign. 00297 /// 00298 /// \return AK_Success if successful 00299 /// \sa 00300 /// - \ref memorymanager 00301 AK_EXTERNAPIFUNC( AKRESULT, Falign )( 00302 AkMemPoolId in_poolId, ///< ID of the memory pool 00303 void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc 00304 ); 00305 00306 //@} 00307 00308 //////////////////////////////////////////////////////////////////////// 00309 /// @name Fixed-Size Blocks Memory Allocation Mode 00310 //@{ 00311 00312 /// Get a block from a Fixed-Size Block type pool. To be used with pools created with AkFixedSizeBlocksMode 00313 /// block management type, along with any of the block allocation types. 00314 /// \return A pointer to the start of the allocated memory (NULL if the system is out of memory) 00315 /// The size of the memory block is always in_uBlockSize, specified in AK::MemoryMgr::CreatePool. 00316 /// \warning This method is not thread-safe. Fixed-Size Block pool access must be protected. 00317 /// \sa 00318 /// - AK::MemoryMgr::CreatePool 00319 /// - AkMemPoolAttributes 00320 /// - \ref memorymanager 00321 AK_EXTERNAPIFUNC( void *, GetBlock )( 00322 AkMemPoolId in_poolId ///< ID of the memory pool 00323 ); 00324 00325 /// Free memory from a Fixed-Size Block type pool. 00326 /// \return AK_Success if successful 00327 /// \warning This method is not thread-safe. Fixed-Size Block pool access must be protected. 00328 /// \sa 00329 /// - \ref memorymanager 00330 AK_EXTERNAPIFUNC( AKRESULT, ReleaseBlock )( 00331 AkMemPoolId in_poolId, ///< ID of the memory pool 00332 void * in_pMemAddress ///< Pointer to the start of memory allocated with Malloc 00333 ); 00334 00335 /// Get block size of blocks obtained with GetBlock() for a given memory pool. 00336 /// The block size is fixed and set when creating a pool with AkFixedSizeBlocksMode. 00337 /// \return Block size 00338 /// \sa 00339 /// - AK::MemoryMgr::CreatePool 00340 /// - AK::MemoryMgr::GetBlock 00341 /// - \ref memorymanager 00342 AK_EXTERNAPIFUNC( AkUInt32, GetBlockSize )( 00343 AkMemPoolId in_poolId ///< ID of the memory pool 00344 ); 00345 00346 /// Called to start profiling memory usage for one thread (the calling thread). 00347 /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage. 00348 AK_EXTERNAPIFUNC( void, StartProfileThreadUsage) ( 00349 AkMemPoolId in_PoolId ///< Pool to profile 00350 ); 00351 00352 /// Called to stop profiling memory usage for the current thread. 00353 /// \return The amount of memory allocated by this thread since \ref StartProfileThreadUsage was called. 00354 /// \note Not implementing this will result in the Soundbank tab of the Wwise Profiler to show 0 bytes for memory usage. 00355 AK_EXTERNAPIFUNC( AkUInt32, StopProfileThreadUsage ) ( 00356 AkMemPoolId in_PoolId ///< Pool to profile 00357 ); 00358 00359 00360 /// Debugging method that verifies if buffer overflow occurred in a specific pool. 00361 /// Called at various moments depending on the DebugFlags set in AkMemSettings. 00362 /// In the default implementation it is not called in Release otherwise will assert if overrun found. 00363 /// Implementation is not mendatory if the MemoryMgr is overriden. 00364 AK_EXTERNAPIFUNC(void, CheckForOverwrite) ( 00365 AkUInt32 in_uPoolID 00366 ); 00367 00368 //@} 00369 } 00370 } 00371 00372 #endif // _AKMEMORYMGR_H_