XMemAllocDefault
The default memory allocation routine.
Syntax
PVOID XMemAllocDefault(
SIZE_T dwSize, ULONGLONG dwAttributes)
Parameters
dwSize
Type: SIZE_T
[in] Size of the memory block that is being requested.
dwAttributes
Type: ULONGLONG
[in] Attributes of the allocation. Refer to XALLOC_ATTRIBUTES.
Return value
Type: PVOID
Returns a pointer to the allocated memory block.
Remarks
Two default functions are exported by the system: XMemAllocDefault and XMemFreeDefault. These represent the initial values of the allocation hooks. If titles choose not to provide their own allocation hooks, these system default allocators will be used instead. If titles desire to provide allocation hooks for the sake of tracking, but do not wish to implement their own allocator, they can call into the default allocator directly.
XMemAllocDefault takes the same parameters as XMemAlloc. It provides the operating-system implementation of XMemAlloc for titles which do not want to hook the behavior, or that want to fall back to the default behavior for cases it does not handle.
The Xbox Platform funnels nearly all allocations through XMemAlloc which provides developers with the opportunity to monitor or handle the memory requirements of the platform. Titles are welcome to supply their own memory managers for some or all of the requests that come through XMemAlloc. For the remainder, the XMemAllocDefault API is used. XMemAllocDefault services allocation requests through one of three mechanisms: HeapAlloc, VirtualAlloc, or a series of internally managed heaps. The decision of which of these three mechanisms to use depends on the type and alignment requirements of the allocation.
Every allocation of type XALLOC_MEMTYPE_HEAP_CACHEABLE will go to HeapAlloc as long as it specifies an alignment <= 16 bytes and a page size of 4 KB.
Otherwise, every allocation of type XALLOC_MEMTYPE_PHYSICAL_* will go to VirtualAlloc. Allocations requesting 4 KB or 64 KB pages will specify the MEM_LARGE_PAGES on the call to VirtualAlloc and allocations requesting 4 MB pages will specify MEM_4MB_PAGES on the call to VirtualAlloc. These flags are needed to ensure that the allocation cannot be relocated in the physical address space.
Otherwise, every allocation that is > 128 KB or that requires alignment of >= 64 KB will go to VirtualAlloc. Allocations of type XALLOC_MEMTYPE_GRAPHICS_* will specify MEM_GRAPHICS on the call to VirtualAlloc, and allocations will specify a page size appropriate for the size specified in the allocation attributes (graphics allocations will be promoted to a minimum page size of 64 KB).
Otherwise, the allocation will be handled by XMemAllocDefault’s internal heap. There are two heaps for each of the 10 documented allocation types; one handles allocations < 4 KB with alignment <= 4 KB (the “small block” heap) and the other handles all other allocations (the “large block” heap). This adds up to 20 heaps total.
XMemAllocDefault Heap Details
- A heap is created on demand, so if there are no allocations of a particular type for a given large/small size, then the heap will never be created.
- Each heap will reserve 2 GB of virtual address space. Therefore, there can be no more than 2 GB of allocations for a given heap.
- Each heap will commit 4 MB pages as required, so every allocation will be fulfilled from a 4 MB page even if 64 KB pages are requested.
- Each heap is single-threaded, so simultaneous allocation and/or free requests from multiple threads will be serialized. Serialization is only required within each individual heap, so simultaneous requests from different heaps can be handled simultaneously.
- Each heap will attempt to pack allocations as densely as possible (while still satisfying alignment constraints) to minimize the amount of memory required to support the heap.
- Each heap can specify its own allocation hysteresis, which determines how aggressively memory will be returned to the operating system when it has been freed. By default each graphics heap specifies a hysteresis of 64 MB, and the XALLOC_MEMTYPE_HEAP_CACHEABLE heaps specify 8 MB (it is unlikely that these are ever used, since cacheable heap allocations typically do not specify an alignment requirement > 16 bytes). If the hysteresis is set to 64 MB, it means that the heap will have to accumulate 64 MB worth of free 4 MB pages before any free pages are returned to the OS. This ensures that the heap code will never need to go back to the OS as long as the amount of memory required fluctuates within the hysteresis amount.
- Heaps start with no committed memory, and request memory from the OS on demand. However, a heap can preallocate memory from the OS if desired by calling XMemPreallocateFreeSpace for that heap. This effectively brings the free page reserve up to the hysteresis limit for that heap.
See also
Requirements
Header: Declared in xmem.h.