> ## 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

设置 XMem 的配置项。

## 语法

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

### 参数

*option*   \_In\_\
类型：[XMEM\_OPTION](/reference/system/xmem/structs/xmem_option)

要设置的选项配置。

### 返回值

类型：void

## 备注

**XMemSetOption** 用于配置 XMem 系统的可选行为。

*eXMEMOPT\_VALIDATE\_XMEMALLOC* (BOOL)<br />
启用对通过调用 XMemAlloc 所返回的内存属性的验证，以确保其满足所请求内存类型的对齐、页大小、页保护和缓存属性。此项旨在于开发阶段使用，以捕获 XMemAlloc 私有实现中的错误。验证逻辑的源代码作为 Microsoft Game Development Kit (GDK) 的一部分提供。有关详细信息，请参阅 `\GXDK\gameKit\Source\amd64\heap.c` 中的 `XmpVerifyXMemAllocRoutine` 函数。

```
       // 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 />
启用在调用 HeapReAlloc 时调用由 `XMemSetWin32HeapTrackingHooks` 配置的 HeapFree 回调。在未设置此选项时，HeapReAlloc 回调将在重新分配完成后被调用，并传入旧地址和新地址。设置此选项后，还会在 HeapReAlloc 调用之前使用旧地址额外调用 HeapFree 回调。

```
       // 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 />
在 `XMemAllocDefault` 为满足分配而进行的每次 `XMemVirtualAlloc` 调用上添加提交标签（例如，当分配请求过大而无法容纳在内部 XMem 堆中时）。提交标签使用 XMemMakeTag('XmVA') 添加。这使开发者能够计算 `XMemAllocDefault` 消耗的总内存量。有关详细信息，请参阅[诊断和内存跟踪](/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 />
设置后，为自定义 XMem 标签分配的存储空间将被设置为指定的大小（以 MB 为单位）。

```
       // 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 />
设置后，如果自定义 XMem 标签的已分配存储被耗尽，将通过 `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 />
`XMemAllocDefault` 使用的内部 XMem 堆最初使用 2MB 页创建，但会配置为在使用 2MB 页扩展堆失败时回退降级为 64KB 页。此标志禁用该降级行为。页大小降级逻辑的源代码作为 Microsoft Game Development Kit (GDK) 的一部分提供。有关详细信息，请参阅 `\GXDK\gameKit\Source\amd64\heap.c` 中的 `XmpAllocateHeapMemory` 函数。

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

<br />

*eXMEMOPT\_XMEMALLOCDEFAULT\_TRAPUSEAFTERFREE* (BOOL)<br />
此选项将 `XMemAllocDefault` 配置为将任何本应由内部 XMem 堆处理的分配提升为 XMemVirtualAlloc 调用。此外，内存使用 VirtualFree(MEM\_DECOMMIT) 释放。虽然这会有意泄漏虚拟地址空间并最终导致分配失败，但它对于捕获释放后使用（use-after-free）错误是有用的诊断辅助手段。提升逻辑的源代码作为 Microsoft Game Development Kit (GDK) 的一部分提供。有关详细信息，请参阅 `\GXDK\gameKit\Source\amd64\heap.c` 中 `XmpTrapUseAfterFree` 变量的用法。

```
       // 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 />
此选项将 `XMemAllocDefault` 配置为对内部 XMem 堆使用 64KB 页而非 2MB 页。此外，使用 64KB 页的堆具有 512KB 而非 2MB 的提交/取消提交粒度。`XMemAllocDefault` 实现的源代码作为 Microsoft Game Development Kit (GDK) 的一部分提供。有关详细信息，请参阅文件 `\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 />
启用后，此选项允许对 `CreateFileMappingA/W` 使用可写标志进行的调用成功。

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

## 要求

**头文件：** xmem.h

**库：** xmem.lib\
**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

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