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

# PlayFab 统一 SDK 中的内存管理

> 使用 PFMemoryHooks 自定义分配器、安全的 XAsyncBlock 生命周期模式和显式句柄清理，管理 PlayFab 统一 SDK 中的内存。

本指南介绍 PlayFab 统一 SDK 中的内存管理方式，包括自定义选项和最佳实践，以避免内存泄漏并确保异步操作的安全处理。

## 概述

PlayFab 统一 SDK 通过支持**自定义分配挂钩**、**显式资源清理**和**安全的异步操作处理**，为开发者提供对内存使用的精确控制。这使其适用于高性能或资源受限的环境，例如游戏和嵌入式平台。

## 自定义内存分配

SDK 允许您使用 `PFMemoryHooks` 定义自定义内存分配和释放函数。这使您能将 SDK 集成到现有的内存管理系统中，例如内存竞技场（arena）、内存池或平台特定的分配器。

### 设置自定义内存挂钩

```cpp theme={null}
void* MyCustomAlloc(size_t size, uint32_t memoryTypeId);
void MyCustomFree(void* ptr, uint32_t memoryTypeId);

PFMemoryHooks memoryHooks = { MyCustomAlloc, MyCustomFree };
PFMemSetFunctions(&memoryHooks);
PFServicesInitialize(nullptr); // Must be called after setting memory hooks
```

**注意事项：**

* 挂钩必须在调用 `PFServicesInitialize` **之前**设置。
* SDK 初始化后**无法**更改它们。
* 如果未设置，SDK 默认使用标准分配（`malloc`/`free`）。

## 异步操作

SDK 中的大多数 API 调用都是异步的。每次异步调用都需要一个有效的 `XAsyncBlock`，且该对象必须在请求持续期间保持存活。

### 安全使用 `XAsyncBlock`

```cpp theme={null}
auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->callback = [](XAsyncBlock* block)
{
    // Retrieve result, then delete asyncBlock if needed
};
StartAsyncPlayFabCall(asyncBlock.get());
asyncBlock.release(); // Ownership passed; handle lifetime carefully
```

**最佳实践：**

* 除非能保证其生命周期，否则不要在栈上分配 `XAsyncBlock`。
* 如果是动态分配的，请释放所有权，并在回调中清理。
* 避免在 lambda 中捕获已失效的引用或指针。

## 资源清理

SDK 使用句柄（例如 `PFEntityHandle`、`PFServiceConfigHandle`），这些句柄在不再需要时**必须**显式关闭。

### 关闭句柄并取消初始化

```cpp theme={null}
PFEntityCloseHandle(entityHandle);
PFServiceConfigCloseHandle(serviceConfigHandle);

// Gracefully uninitialize the SDK
XAsyncBlock async{};
PFServicesUninitializeAsync(&async);
XAsyncGetStatus(&async, true); // Blocks until cleanup completes
```

**重要事项：**

* 始终关闭 PlayFab 句柄以防止泄漏。
* 在关闭前等待 `PFServicesUninitializeAsync` 完成。

## 最佳实践

* **尽早设置内存挂钩**：在任何其他 PlayFab API 调用之前。
* **避免内存泄漏**：关闭句柄并小心管理异步资源。
* **使用内存分析器**：尤其是在内存预算紧张的平台上。
* **使用池化分配器**：用于性能关键或频繁的分配。

## 另请参阅

* [异步操作](/services/playfab/sdks/unified-sdk/async-model)
* [内存管理](/services/playfab/sdks/unified-sdk/memory-management)
* [跟踪与诊断](/services/playfab/sdks/unified-sdk/debug-trace)


## Related topics

- [PlayFab 统一 SDK](/zh-CN/services/playfab/sdks/unified-sdk/overview.md)
- [在 PlayFab 统一 SDK 中进行异步调用](/zh-CN/services/playfab/sdks/unified-sdk/async-model.md)
- [在 PlayFab 统一 SDK 中进行调试跟踪](/zh-CN/services/playfab/sdks/unified-sdk/debug-trace.md)
- [XBOX GDK 游戏的内存系统](/zh-CN/build/console-features/memory/index.md)
- [内存钩子](/zh-CN/services/playfab/sdks/c/memory.md)