> ## 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](/zh-TW/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` 所耗用的記憶體總量。如需詳細資訊，請參閱[診斷與記憶體追蹤](/zh-TW/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) 釋放。雖然這會刻意流失虛擬位址空間，最終導致配置失敗，但這是攔截釋放後使用錯誤的實用診斷輔助工具。提升邏輯的原始程式碼會作為 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。`XMemAllocDefalt` 實作的原始程式碼會作為 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](/zh-TW/reference/system/xmem/xmem_members)
[XMemMakeTag](/zh-TW/reference/system/xmem/functions/xmemmaketag)
[XError](/zh-TW/reference/system/xerror/xerror_members)


## Related topics

- [XMemSetOption](/reference/system/xmem/functions/xmemsetoption.md)
- [XMEM_OPTION](/reference/system/xmem/structs/xmem_option.md)