Version
menu_open
Wwise SDK 2024.1.0
AkTempAllocDefs.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 /// namespace for handling temp-allocations (incl. stack allocs)
29 
30 #pragma once
31 
32 #include <AK/SoundEngine/Common/AkSoundEngineExport.h>
33 #include <AK/SoundEngine/Common/AkTypes.h>
34 
35 namespace AK
36 {
37  /// TempAlloc namespace.
38  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
39  /// \sa
40  /// - \ref goingfurther_optimizingmempools_tempallocs
41  namespace TempAlloc
42  {
43  ////////////////////////////////////////////////////////////////////////
44  /// @name TempAlloc systems
45  //@{
46 
47  /// Temp-alloc memory statistics. Whenever these are fetched, they represent the last completed temp-alloc "tick".
48  /// \remarks These statistics are not collected in the Release configuration of the memory mgr.
49  struct Stats
50  {
51  AkUInt32 uMemUsed; ///< Used memory (in bytes).
52  AkUInt32 uMemAllocated; ///< Allocated memory (in bytes).
53  AkUInt32 uBlocksUsed; ///< Number of individual blocks used.
54 
55  AkUInt32 uPeakMemUsed; ///< The peak value for uMemUsed since initialization.
56  AkUInt32 uPeakMemAllocated; ///< The peak value for uMemAllocated since initialization.
57  AkUInt32 uPeakBlocksUsed; ///< The peak value for uBlocksUsed since initialization.
58  AkUInt32 uPeakBlockUsed; ///< The peak amount of used memory in any single block since initialization.
59  };
60 
61  /// IDs of temporary memory pools used by the sound engine.
62  enum Type
63  {
64  Type_AudioRender,
65  Type_NUM,
66  };
67 
68  /// Lifetimes of temporary allocations available.
69  enum Lifetime
70  {
71  Lifetime_CurrentTick = 0,
72  Lifetime_DoubleTick = 1,
73  Lifetime_NUM,
74  };
75 
76  /// Initialization settings for temporary-memory pools. Separate settings are specified for each temporary-memory pool.
77  /// \remarks The debug options are intended for monitoring and analyzing potential issues in usage of the TempAlloc system during development. Their functionality is specifically removed in Release configurations of the AkMemoryMgr.
78  struct InitSettings
79  {
80  AkUInt32 uMinimumBlockCount; ///< The number of blocks of memory the system is initialized with and is the minimum kept around forever. Defaults to 1. Higher values increase upfront memory use, but can reduce, or eliminate, the creation and destruction of memory blocks over time.
81  AkUInt32 uMinimumBlockSize; ///< The minimum size of each block. If a new allocation requests a new block of memory, then the new block is the size of the requested allocation times four, and then rounded up to the next multiple of this value. Defaults to 512 KiB.
82  AkUInt32 uMaximumUnusedBlocks; ///< The maximum number of blocks that the system keeps in an unused state, and avoids freeing. Defaults to 1. Higher values do not increase the peak memory use, but do prevent unused memory from being freed, in order to reduce creation and destruction of memory blocks.
83 
84  bool bDebugDetailedStats; ///< Enable to track detailed stats and include them in the detailed stat dump. Detailed stats include the size and quantity of each type of allocation from the system. Disabled by default.
85  bool bDebugClearMemory; ///< Enable to clear any allocation to a deterministic garbage value. Useful to make sure memory is initialized properly. Disabled by default.
86  bool bDebugEnableSentinels; ///< Enable to write out sentinels between most allocations to help detect memory overwrites, verified at the end of a tick. Enabled by default. Increases memory usage of blocks slightly.
87  bool bDebugFlushBlocks; ///< Enable to forcefully release all blocks at the end of a tick and recreate them from scratch every tick. Useful to ensure stale memory is not being accessed. Disabled by default. This might interfere with some stats reporting due to blocks being released between ticks.
88  bool bDebugStandaloneAllocs; ///< Enable to force the block size to be as small as possible for each allocation (smaller than can be achieved by just setting uMinimumBlockSize to very low values). Useful to investigate memory overruns in-depth, especially in conjunction with other options like bDebugFlushBlocks and the MemoryMgr's stomp allocator. If enabled, bDebugDetailedStats and bDebugEnableSentinels will be disabled. Greatly increases CPU and memory usage.
89  };
90 
91  /// Get simple statistics for a given temporary-memory pool
92  AK_EXTERNAPIFUNC(void, GetStats)(
93  Type in_eType, ///< Temporary-memory pool type.
94  Stats& out_stats ///< Returned statistics.
95  );
96 
97  /// Get a detailed listing of the allocations into the temp-alloc pool, and output them to a file.
98  /// \note TempAllocInitSettings::bTrackDetailedStats must be enabled for the specified type to get detailed information about the underlying allocs. Otherwise, only the simple stats are listed.
99  AK_EXTERNAPIFUNC(void, DumpTempAllocsToFile)(
100  Type in_eType, ///< Temporary-memory pool type.
101  const AkOSChar* pszFilename ///< Filename.
102  );
103  }
104 
105  /// BookmarkAlloc namespace.
106  /// \remarks The functions in this namespace are thread-safe, unless stated otherwise.
107  /// \sa
108  /// - \ref goingfurther_optimizingmempools_bookmarkalloc
109  namespace BookmarkAlloc
110  {
111  ////////////////////////////////////////////////////////////////////////
112  /// @name BookmarkAlloc systems
113  //@{
114 
115  /// Bookmark-allocator memory statistics. Whenever these are fetched, they represent whatever happened since the last tick
116  /// \remarks These statistics are not collected in the Release configuration of the memory mgr.
117  struct Stats
118  {
119  AkUInt32 uRecentPeakMemUsed; ///< Peak used memory in a single BookmarkAlloc region since the last tick (in bytes).
120  AkUInt32 uRecentBlocksFetched; ///< Number of times a block was fetched from the cache, not including the base block. High values here may indicate that block sizes need to be larger.
121  AkUInt32 uMemAllocated; ///< Currently allocated memory (in bytes).
122  AkUInt32 uBlocksAllocated; ///< Number of individual blocks currently allocated.
123 
124  AkUInt32 uPeakMemUsed; ///< The peak value for uRecentPeakMemUsed since initialization.
125  AkUInt32 uPeakMemAllocated; ///< The peak value for uMemAllocated since initialization.
126  AkUInt32 uPeakBlocksFetched; ///< The peak value for uRecentBlocksFetched since initialization.
127  AkUInt32 uPeakBlocksAllocated; ///< The peak value for uBlocksAllocated since initialization.
128  AkUInt32 uPeakBlockSize; ///< The peak size of any single block since initialization.
129  };
130 
131  /// Initialization settings for Bookmark-allocator memory.
132  /// \remarks The debug options are intended for monitoring and analyzing potential issues in usage of the BookmarkAlloc system during development. Their functionality is specifically removed in Release configurations of the AkMemoryMgr.
133  struct InitSettings
134  {
135  AkUInt32 uMinimumBlockCount; ///< The number of blocks of memory the system is initialized with and is the minimum kept around forever. Defaults to 1. Higher values increase upfront memory use, but can reduce, or eliminate, the creation and destruction of memory blocks over time.
136  AkUInt32 uMinimumBlockSize; ///< The minimum size of each block. If a new allocation requests a new block of memory, then the new block is the size of the requested allocation times four, and then rounded up to the next multiple of this value. Defaults to 64 KiB.
137  AkUInt32 uMaximumUnusedBlocks; ///< The maximum number of blocks that the system keeps in an unused state, and avoids freeing. Defaults to 1. Higher values do not increase the peak memory use, but do prevent unused memory from being freed, in order to reduce creation and destruction of memory blocks.
138 
139  bool bDebugDetailedStats; ///< Enable to track detailed stats, specifically collection of Stats::uRecentPeakMemUsed. Enabled by default.
140  bool bDebugClearMemory; ///< Enable to clear any allocation to a deterministic garbage value during allocs, and after the stack is rewound to a bookmark. Useful to make sure memory is initialized properly. Disabled by default.
141  bool bDebugEnableSentinels; ///< Enable to write out sentinels between most allocations to help detect memory overwrites, which are verified at the termination of a bookmark alloc region. Enabled by default. Increases memory usage of blocks slightly.
142  bool bDebugStandaloneAllocs; ///< Enable to force the block size to be as small as possible for each allocation (smaller than can be achieved by just setting uMinimumBlockSize to very low values). Useful to investigate memory overruns in-depth, especially in conjunction with the MemoryMgr's stomp allocator. If enabled, bDebugEnableSentinels will be disabled. Greatly increases CPU and memory usage.
143  };
144 
145  /// Get simple statistics for the Bookmark allocator
146  AK_EXTERNAPIFUNC(void, GetStats)(
147  Stats& out_stats ///< Returned statistics.
148  );
149  }
150 }
151 
AK::BookmarkAlloc::Stats::uPeakMemAllocated
AkUInt32 uPeakMemAllocated
The peak value for uMemAllocated since initialization.
Definition: AkTempAllocDefs.h:125
AK::TempAlloc::InitSettings::bDebugDetailedStats
bool bDebugDetailedStats
Enable to track detailed stats and include them in the detailed stat dump. Detailed stats include the...
Definition: AkTempAllocDefs.h:84
AK::TempAlloc::InitSettings::uMinimumBlockCount
AkUInt32 uMinimumBlockCount
The number of blocks of memory the system is initialized with and is the minimum kept around forever....
Definition: AkTempAllocDefs.h:80
AK
Definition of data structures for AkAudioObject.
Definition: AkWwiseSDKVersion.cs:31
AK::BookmarkAlloc::InitSettings::bDebugStandaloneAllocs
bool bDebugStandaloneAllocs
Enable to force the block size to be as small as possible for each allocation (smaller than can be ac...
Definition: AkTempAllocDefs.h:142
AK::TempAlloc::InitSettings::bDebugClearMemory
bool bDebugClearMemory
Enable to clear any allocation to a deterministic garbage value. Useful to make sure memory is initia...
Definition: AkTempAllocDefs.h:85
AK::BookmarkAlloc::Stats::uBlocksAllocated
AkUInt32 uBlocksAllocated
Number of individual blocks currently allocated.
Definition: AkTempAllocDefs.h:122
AK::BookmarkAlloc::InitSettings::bDebugClearMemory
bool bDebugClearMemory
Enable to clear any allocation to a deterministic garbage value during allocs, and after the stack is...
Definition: AkTempAllocDefs.h:140
AK::TempAlloc::Stats::uMemAllocated
AkUInt32 uMemAllocated
Allocated memory (in bytes).
Definition: AkTempAllocDefs.h:52
AK::BookmarkAlloc::Stats::uPeakBlocksFetched
AkUInt32 uPeakBlocksFetched
The peak value for uRecentBlocksFetched since initialization.
Definition: AkTempAllocDefs.h:126
AK::BookmarkAlloc::InitSettings::bDebugEnableSentinels
bool bDebugEnableSentinels
Enable to write out sentinels between most allocations to help detect memory overwrites,...
Definition: AkTempAllocDefs.h:141
AK::TempAlloc::Stats::uPeakBlockUsed
AkUInt32 uPeakBlockUsed
The peak amount of used memory in any single block since initialization.
Definition: AkTempAllocDefs.h:58
AK_EXTERNAPIFUNC
#define AK_EXTERNAPIFUNC(_type, _name)
Definition: AkSoundEngineExport.h:81
AK::TempAlloc::InitSettings::bDebugEnableSentinels
bool bDebugEnableSentinels
Enable to write out sentinels between most allocations to help detect memory overwrites,...
Definition: AkTempAllocDefs.h:86
AK::BookmarkAlloc::Stats::uPeakBlockSize
AkUInt32 uPeakBlockSize
The peak size of any single block since initialization.
Definition: AkTempAllocDefs.h:128
AK::TempAlloc::Stats::uPeakBlocksUsed
AkUInt32 uPeakBlocksUsed
The peak value for uBlocksUsed since initialization.
Definition: AkTempAllocDefs.h:57
AK::TempAlloc::InitSettings::uMaximumUnusedBlocks
AkUInt32 uMaximumUnusedBlocks
The maximum number of blocks that the system keeps in an unused state, and avoids freeing....
Definition: AkTempAllocDefs.h:82
AK::BookmarkAlloc::InitSettings::bDebugDetailedStats
bool bDebugDetailedStats
Enable to track detailed stats, specifically collection of Stats::uRecentPeakMemUsed....
Definition: AkTempAllocDefs.h:139
AK::BookmarkAlloc::InitSettings::uMinimumBlockCount
AkUInt32 uMinimumBlockCount
The number of blocks of memory the system is initialized with and is the minimum kept around forever....
Definition: AkTempAllocDefs.h:135
AkOSChar
char AkOSChar
Generic character string.
Definition: AkTypes.h:60
AK::TempAlloc::Stats::uMemUsed
AkUInt32 uMemUsed
Used memory (in bytes).
Definition: AkTempAllocDefs.h:51
AK::BookmarkAlloc::GetStats
AKSOUNDENGINE_API void GetStats(Stats &out_stats)
Get simple statistics for the Bookmark allocator.
AK::TempAlloc::GetStats
AKSOUNDENGINE_API void GetStats(Type in_eType, Stats &out_stats)
Get simple statistics for a given temporary-memory pool.
AK::BookmarkAlloc::InitSettings::uMaximumUnusedBlocks
AkUInt32 uMaximumUnusedBlocks
The maximum number of blocks that the system keeps in an unused state, and avoids freeing....
Definition: AkTempAllocDefs.h:137
AK::TempAlloc::Type
Type
IDs of temporary memory pools used by the sound engine.
Definition: AkTempAllocDefs.h:63
AK::BookmarkAlloc::Stats::uMemAllocated
AkUInt32 uMemAllocated
Currently allocated memory (in bytes).
Definition: AkTempAllocDefs.h:121
AK::BookmarkAlloc::InitSettings::uMinimumBlockSize
AkUInt32 uMinimumBlockSize
The minimum size of each block. If a new allocation requests a new block of memory,...
Definition: AkTempAllocDefs.h:136
AK::TempAlloc::Stats::uBlocksUsed
AkUInt32 uBlocksUsed
Number of individual blocks used.
Definition: AkTempAllocDefs.h:53
AK::TempAlloc::Stats::uPeakMemAllocated
AkUInt32 uPeakMemAllocated
The peak value for uMemAllocated since initialization.
Definition: AkTempAllocDefs.h:56
AK::TempAlloc::InitSettings::bDebugStandaloneAllocs
bool bDebugStandaloneAllocs
Enable to force the block size to be as small as possible for each allocation (smaller than can be ac...
Definition: AkTempAllocDefs.h:88
AK::BookmarkAlloc::Stats::uRecentPeakMemUsed
AkUInt32 uRecentPeakMemUsed
Peak used memory in a single BookmarkAlloc region since the last tick (in bytes).
Definition: AkTempAllocDefs.h:119
AK::TempAlloc::DumpTempAllocsToFile
AKSOUNDENGINE_API void DumpTempAllocsToFile(Type in_eType, const AkOSChar *pszFilename)
AK::TempAlloc::InitSettings::bDebugFlushBlocks
bool bDebugFlushBlocks
Enable to forcefully release all blocks at the end of a tick and recreate them from scratch every tic...
Definition: AkTempAllocDefs.h:87
AK::BookmarkAlloc::Stats::uPeakMemUsed
AkUInt32 uPeakMemUsed
The peak value for uRecentPeakMemUsed since initialization.
Definition: AkTempAllocDefs.h:124
AK::TempAlloc::InitSettings::uMinimumBlockSize
AkUInt32 uMinimumBlockSize
The minimum size of each block. If a new allocation requests a new block of memory,...
Definition: AkTempAllocDefs.h:81
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkNumeralTypes.h:38
AK::BookmarkAlloc::Stats::uPeakBlocksAllocated
AkUInt32 uPeakBlocksAllocated
The peak value for uBlocksAllocated since initialization.
Definition: AkTempAllocDefs.h:127
AK::TempAlloc::Lifetime
Lifetime
Lifetimes of temporary allocations available.
Definition: AkTempAllocDefs.h:70
AK::TempAlloc::Stats::uPeakMemUsed
AkUInt32 uPeakMemUsed
The peak value for uMemUsed since initialization.
Definition: AkTempAllocDefs.h:55
AK::BookmarkAlloc::Stats::uRecentBlocksFetched
AkUInt32 uRecentBlocksFetched
Number of times a block was fetched from the cache, not including the base block. High values here ma...
Definition: AkTempAllocDefs.h:120

Cette page a-t-elle été utile ?

Besoin d'aide ?

Des questions ? Des problèmes ? Besoin de plus d'informations ? Contactez-nous, nous pouvons vous aider !

Visitez notre page d'Aide

Décrivez-nous de votre projet. Nous sommes là pour vous aider.

Enregistrez votre projet et nous vous aiderons à démarrer sans aucune obligation !

Partir du bon pied avec Wwise