XMemSetAllocationHooks

Used by titles to register memory allocation hooks.

Syntax

void XMemSetAllocationHooks(
         LPXMEMALLOC_ROUTINE lpAllocRoutine,
         LPXMEMFREE_ROUTINE lpFreeRoutine
)  

Parameters

lpAllocRoutine
Type: LPXMEMALLOC_ROUTINE 

[in] The title’s allocation function.

lpFreeRoutine
Type: LPXMEMFREE_ROUTINE 

[in] The title’s free function.

Return value

None.

Remarks

Two default functions are exported by kernelx: 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.

Unlike Xbox 360, where all libraries were compiled into your title as static libraries and it was possible to simply define your own XMemAlloc and XMemFree implementations to hook them, libraries on Xbox One are mostly DLL-based or exist in the kernel of the title partition.

Because of this, to hook XMemAlloc and XMemFree from your own code you must call XMemSetAllocationHooks to enable interception of these calls:

void XMemSetAllocationHooks(
    _In_ LPXMEMALLOC_ROUTINE lpAllocRoutine,
    _In_ LPXMEMFREE_ROUTINE lpFreeRoutine
    );  

XMEMALLOC_ROUTINE and XMEMFREE_ROUTINE are function prototypes which have the same signature as shown for XMemFree and XMemAlloc in the API documentation above. To unwire your hooks, call the same routine with nullptr passed in for both parameters.

It is important to provide an implementation for both XMemFree and XMemAlloc if you hook them; hooking only one of them will be considered an error.

If you hook the APIs, be sure that this is the first thing that your title does, otherwise you may miss allocations.

Calling XMemAllocDefault and XMemFreeDefault from Hooked API Calls

It is acceptable to only partially implement your own replacement for XMemAlloc and XMemFree, and pass any cases that you do not handle through to the default implementations –XMemAllocDefault and XMemFreeDefault. However, take care to ensure that you maintain the pairing of these functions; whenever you call XMemAllocDefault to allocate memory, it must be freed by a call to XMemFreeDefault.

The easiest way to handle this behavior is to:

• Check the allocator ID passed to you in the dwAttributes parameter. If you know the allocator, handle it yourself.
• Otherwise, pass the call onto the default version of the function.

You may also choose to only handle allocations of certain types, or handle allocations for middleware and the operating system yourself, provided that you honor all of the parameters specified in dwAttributes for alignment, memory type and the size of the memory page that is fulfilling the request.

It is also acceptable to only override XMemAlloc and XMemFree to track memory allocations.

Requirements

Header: Declared in xmem.h.