| RFC-0161：Sense Allocator API | |
|---|---|
| 状态 | 已接受 |
| 领域 |
|
| 说明 | 之前用于进行 API 校准的 smooth Allocator 的 API 设计文档。 |
| Gerrit 更改 | |
| 作者 | |
| 审核人 | |
| 提交日期（年-月-日） | 2021-03-19 |
| 审核日期（年-月-日） | 2021-04-05 |
之前的 API 设计文档
此 RFC 之前是作为 API 设计文档提交的，并在 API 设计文档模板被废弃后转换为 RFC。
总结
本文档提出了一项计划，用于将 View 的 Image 资源分配提取到单独的协议中。
目标和应用场景
Allocator API 旨在改进现有的图片分配流程，使其与即将发生的变更兼容。
扩展了“Sense::Session”中分配的 BufferCollection 资源的范围。一个 BufferCollection 可用于在多个 smooth::Sessions 和我们即将发布的 2D API Flatland 会话中创建图像资源。
将缓冲区分配与 smooth::Session 分离可使协议的目的明确。分配器仅处理缓冲区分配，而 smooth::Sessions 用于演示和绘制。
分配器可用于我们的 3D API 以及即将推出的 2D API。这样可以实现更复杂的图形使用。
使用此 API，更复杂的用户可以在其独立的 Scenic::Sessions 之间共享图片资源。这目前无法实现，并且常常需要重新分配。
设计
我们的建议主要是将缓冲区注册和取消注册功能从 smooth::Session 移至新协议。请参阅下文，了解提议的协议。
library fuchsia.ui.composition;
/// A typed wrapper for an eventpair, representing the registry endpoint of a buffer collection.
resource struct BufferCollectionExportToken {
zx.handle:EVENTPAIR value;
};
/// A typed wrapper for an eventpair, representing the Image import endpoint of a buffer
/// collection.
resource struct BufferCollectionImportToken {
zx.handle:EVENTPAIR value;
};
protocol Allocator {
/// A BufferCollection is a set of VMOs created by Sysmem and shared by a number of
/// participants, one of which is the Flatland Renderer. Some content, such as Images, use a
/// BufferCollection as their backing memory.
///
/// Clients can send `export_token` to register buffer collections with Allocator to be used
/// later in [`fuchsia.ui.composition/Flatland`] instances or other Scenic APIs. For
/// example, by passing a [`BufferCollectionImportToken`] containing the matching peer of
/// [`BufferCollectionExportToken`], they can create image resources via
/// [`fuchsia.ui.composition/Flatland.CreateImage`]. Clients should wait for the response
/// before using `import_token`.
///
/// Flatland participates in the allocation of buffers by setting constraints on the
/// BufferCollection referenced by `buffer_collection_token`. It will not block on buffers
/// being allocated until the client creates content using the BufferCollection.
///
/// The buffer collection registered with `export_token` is available and kept alive as long
/// as the client holds a valid [`BufferCollectionImportToken`]. They will be garbage collected
/// when all [`BufferCollectionImportToken`]s are closed and all the associated Image resources
/// are released.
RegisterBufferCollection(BufferCollectionExportToken export_token,
fuchsia.sysmem.BufferCollectionToken buffer_collection_token)
-> () error RegisterBufferCollectionError;
};
图 1 - 映像创建流程
请注意，不再需要缓冲区取消注册。这可以通过丢弃客户端上的所有 BufferCollectionImportToken 实例来隐式完成。考虑到许多客户端在意外关停时会遇到取消注册流程，这可以更好地防止内存泄漏。
现有的缓冲区注册功能要求客户端定义一个唯一 ID 来引用 BufferCollection。取而代之的是 EVENTPAIR，客户端可以根据需要进行多次轻松复制操作。请参阅下方的现有流程。
protocol Session {
RegisterBufferCollection(uint32 buffer_id, fuchsia.sysmem.BufferCollectionToken token);
DeregisterBufferCollection(uint32 buffer_id);
};
为着陆建议设计所做的工作正在进行，必要的重构已经完成。如需了解实际更改，请参阅 fxr/498558 和 fxr/499479。
易用性
通过 Allocator API，我们可以采用不同的方式来实现现有功能，这对客户端而言更简单。
- 客户端创建 EVENTPAIR，而不是确定唯一 ID。
- 客户端可以丢弃事件对的另一端，而不是显式调用具有相同唯一 ID 的 DeregisterBufferCollection。
- 客户端可以在多个 smooth::Sessions 中复制并使用事件对的另一端，以创建图片资源。
请参见下面的示例，了解 scene::Session 中的用法。
fuchsia::ui::composition::AllocatorPtr scenic_allocator;
fuchsia::sysmem::BufferCollectionTokenSyncPtr token;
auto ref_pair = allocation::BufferCollectionImportExportTokens::New();
scenic::SessionPtr session;
scenic_allocator->RegisterBufferCollection(std::move(ref_pair.export_token), std::move(token),
[&]() {
session->Enqueue(scenic::NewCreateImage3Cmd(
image_id, width, height,
std::move(ref_pair.import_token), vmo_index));
});
测试
我们计划围绕我们的 API 添加大量单元测试。需要将分配器与 smooth::Session 结合使用的集成测试可以通过转换我们的树内像素测试来完成。
性能注意事项
Allocator API 不会添加任何其他 API 调用。它可以让客户端免于执行 DeregisterBufferCollection 调用。
安全注意事项
Allocator API 依靠 EVENTPAIR 功能解决安全问题。EVENTPAIR 的唯一性以及创建时与其他端点的强关联可确保恶意客户端无法劫持和访问底层缓冲区。如果他们以某种方式获取 EVENTPAIR，他们只能显示此图片，而无法修改或读取它。
缺点和替代方案
Allocator API 提案有两个主要改进点，其中任一改进都可以替换为现有协议和流程。
- 我们可以继续使用唯一 ID 而非事件对来引用缓冲区集合。我们可以期望客户端选择唯一的集合标识符，也可以从注册调用返回唯一的集合标识符。
- 选择唯一标识符需要进行同步，因为客户端要查找有效的标识符，并等待 Allocator 确认后再使用。
- 唯一标识符很容易被恶意客户端劫持。
- 我们需要显式 DeregisterBufferCollection() 调用。
- 我们可以将 Allocator 保留在 Views::Session 和 Flatland 实例中，而不是公开新协议。
- 处理多个会话的复杂客户端仍然存在如下限制：在注册的会话之外，只使用缓冲区收集。