> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XMemSetOption

> XMemSetOption

# XMemSetOption

Sets a configuration setting for XMem.

## Syntax

```cpp theme={null}
void XMemSetOption(  
         XMEM_OPTION option  
)  
```

### Parameters

*option*   \_In\_\
Type: [XMEM\_OPTION](/reference/system/xmem/structs/xmem_option)

The option configuration to set.

### Return value

Type: void

## Remarks

**XMemSetOption** is used to configure optional behaviors of the XMem system.

*eXMEMOPT\_VALIDATE\_XMEMALLOC* (BOOL)<br />
Enables verification of the memory properties returned from a call to XMemAlloc to ensure that it meets the alignment, page size, page protections, and cache attributes of the requested memory type.  This is intended to be used at development time to catch errors in private implementations of XMemAlloc. Source code for the verification logic is provided as part of the Microsoft Game Development Kit (GDK). For more information, see the `XmpVerifyXMemAllocRoutine` function in `\GXDK\gameKit\Source\amd64\heap.c`.

```
       // Enable memory validation on XMemAlloc
       XMEM_OPTION option;
       option.Option = eXMEMOPT_VALIDATE_XMEMALLOC;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_RAISE\_HEAPFREE\_CALLBACK\_ON\_REALLOC* (BOOL)<br />
Enables calling the HeapFree callback configured by `XMemSetWin32HeapTrackingHooks` when HeapReAlloc has been called.  Without this option the HeapReAlloc callback is called after the realloc has occurred with the old and new address.  When this option is set the HeapFree callback will additionally be called prior to the HeapReAlloc call with the old address.

```
       // Enable calling the HeapFree callback on HeapReAlloc
       XMEM_OPTION option;
       option.Option = eXMEMOPT_RAISE_HEAPFREE_CALLBACK_ON_REALLOC;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_XMEMALLOCDEFAULT\_TAG\_VIRTUALALLOC* (BOOL)<br />
Enables the addition of a commit tag on every call to `XMemVirtualAlloc` that is made by `XMemAllocDefault` to satisfy an allocation (for example, when the allocation request is too large to fit within an internal XMem heap).  The commit tag is added with XMemMakeTag('XmVA').  This enables a developer to compute the total amount of memory consumed by `XMemAllocDefault`.  For more information see [Diagnostics and memory tracking](/build/console-features/memory/system-memory-diagnostics).

```
       // Enable commit tagging on XMemAllocDefault
       XMEM_OPTION option;
       option.Option = eXMEMOPT_XMEMALLOCDEFAULT_TAG_VIRTUALALLOC;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_SET\_XMEM\_TAG\_TREE\_SIZE* (INT)<br />
When set, the allocated storage space for custom XMem Tags will be set to the specified size in megabytes.

```
       // Configure XMem to use the specified size for XMem Tags
       XMEM_OPTION option;
       option.Option = eXMEMOPT_SET_XMEM_TAG_TREE_SIZE;
       option.u.Int = 4; // 4MB
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_XMEM\_WARN\_WHEN\_TAG\_TREE\_FULL* (BOOL)<br />
When set, if the allocated storage for custom XMem Tags is exhausted, a runtime warning will be raised through `XError`.

```
       // Configure XMem to raise a warning when XMem Tags storage space has been exhausted.
       XMEM_OPTION option;
       option.Option = eXMEMOPT_XMEM_WARN_WHEN_TAG_TREE_FULL;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_XMEMALLOCDEFAULT\_DISABLEPAGESIZEDEMOTION* (BOOL)<br />
The internal XMem heaps used by `XMemAllocDefault` are initially created using 2MB pages but are configured to fallback to demote to 64KB pages if they encounter a failure to grow the heap using 2MB pages.  This flag disables the demotion behavior.  Source code for the page size demotion logic is provided as part of the Microsoft Game Development Kit (GDK). For more information, see the `XmpAllocateHeapMemory` function in `\GXDK\gameKit\Source\amd64\heap.c`

```
       // Disables page size demotion
       XMEM_OPTION option;
       option.Option = eXMEMOPT_XMEMALLOCDEFAULT_DISABLEPAGESIZEDEMOTION;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_XMEMALLOCDEFAULT\_TRAPUSEAFTERFREE* (BOOL)<br />
This option configures `XMemAllocDefault` to promote any allocations that would normally be serviced by the internal XMem heaps to XMemVirtualAlloc calls.  Furthermore the memory is freed using VirtualFree(MEM\_DECOMMIT).  While this intentionally leaks virtual address space and will eventually lead to an allocation failure, it is a useful diagnostics aid for catching use-after-free errors.  Source code for promotion logic is provided as part of the Microsoft Game Development Kit (GDK). For more information, see the usage of the `XmpTrapUseAfterFree` variable in `\GXDK\gameKit\Source\amd64\heap.c`

```
       // Enable trapping use-after-free scenarios with XMemAllocDefault
       XMEM_OPTION option;
       option.Option = eXMEMOPT_XMEMALLOCDEFAULT_TRAPUSEAFTERFREE;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_XMEMALLOCDEFAULT\_USE64KPAGES* (BOOL)<br />
This option configures `XMemAllocDefault` to use 64KB pages instead of 2MB pages for the internal XMem heaps.  Additionally, heaps using 64KB pages have a commit/decommit granularity of 512KB instead of 2MB.  Source code for implementation of `XMemAllocDefalt` is provided as part of the Microsoft Game Development Kit (GDK). For more information, see the file `\GXDK\gameKit\Source\amd64\heap.c`

```
       // Configure XMem heaps to use 64KB pages and 512KB commit/decommit granularity
       XMEM_OPTION option;
       option.Option = eXMEMOPT_XMEMALLOCDEFAULT_USE64KPAGES;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

<br />

*eXMEMOPT\_ALLOW\_WRITEABLE\_FILEMAPPINGS* (BOOL)<br />
When enabled, this option allows calls to `CreateFileMappingA/W` to succeed when called with writable flags.

```
       // Configure XMem to allow writeable file mappings
       XMEM_OPTION option;
       option.Option = eXMEMOPT_ALLOW_WRITEABLE_FILEMAPPINGS;
       option.u.Bool = TRUE;
       XMemSetOption(option);
```

## Requirements

**Header:** xmem.h

**Library:** xmem.lib\
**Supported Platforms**: XBOX One family consoles and XBOX Series consoles

## See also

[XMem](/reference/system/xmem/xmem_members)
[XMemMakeTag](/reference/system/xmem/functions/xmemmaketag)
[XError](/reference/system/xerror/xerror_members)


## Related topics

- [XMEM_OPTION](/reference/system/xmem/structs/xmem_option.md)
- [XMemVirtualQuery](/reference/system/xmem/functions/xmemvirtualquery.md)
- [XMEM_OPTIONS](/reference/system/xmem/enums/xmem_options.md)
- [PartySetTranscriptionOptionsCompletedStateChange](/services/playfab/multiplayer/networking/reference/structs/partysettranscriptionoptionscompletedstatechange.md)
- [PartySetTextChatOptionsCompletedStateChange](/services/playfab/multiplayer/networking/reference/structs/partysettextchatoptionscompletedstatechange.md)