MobileGL/docs/CS_Refactor/HandleSessionGeneration.md

MobileGL C/S: Handle / Session / Generation 统一语义

状态：Phase 0 契约文档（与 C_S_REFACTOR_PLAN.md §5 一一对应） 范围：FullServer、Client、BackendObject、UtilRuntime 共用的对象标识语义 读者：所有实现 BFA / 外部协议的模块

---

1. ID 层级

DisplayId
  └─ SharedGroupId
       └─ SessionId
            └─ ObjectHandle（共享对象在 SharedGroup 级；上下文私有对象在 Session 级）

所有 ID 均为 uint64_t，由 FullServer 在进程生命周期内分配，不复用。0 保留为无效 ID。

ID	分配者	生命周期	语义
MobileGLDisplayId	FullServer (EGL)	eglGetDisplay → eglTerminate	一个 EGLDisplay 的句柄；持有 backend device
MobileGLSharedGroupId	FullServer	首个无 share 的 context 创建 → group 内全部 context 销毁	共享对象表、ShareGroup 级 backend native 资源
MobileGLSessionId	FullServer	eglCreateContext → eglDestroyContext	一个 GL context；持有 current bindings / error queue
MobileGLBackendHandle	FullServer	对象创建 → 对象销毁	不透明对象句柄，与 GL name 解耦

2. 归属规则

状态	归属
EGL display / config / surface	DisplayId
GL 共享对象表（buffer/texture/sampler/VAO/program/shader/pipeline/FBO/RBO/TF）	SharedGroupId
上下文私有对象（default FBO/VAO/texture 0、query、sync 等）	SessionId
current bindings / render state / viewport / error queue	SessionId
backend native 共享资源（VkBuffer/VkImage/pipeline/sampler）	SharedGroupId
command pool / descriptor pool / frame tracking / deferred release	SessionId
硬件设备 / loader	DisplayId

3. ObjectHandle 模型

ObjectHandle = uint64_t
  - FullServer 分配，进程生命周期内不复用
  - 共享对象：同一 handle 在 SharedGroup 内所有 Session 可见
  - 上下文私有对象：仅所属 Session 有效
  - 与 GL name 解耦
  - 映射：
      共享对象     (SharedGroupId, ObjectKind, GLname)  → handle
      上下文私有  (SessionId, ObjectKind, name/slot)   → handle

设计理由：

• 天然支持 name 0 默认对象、proxy texture、texture view、reserved-but-not-materialized 对象；
• 避免 SharedPtr<T> / 裸指针跨插件边界；
• 未来 share group 语义扩展不需要改接口。

4. 映射表（FullServer 拥有）

FullServer 维护以下 Registry（线程安全）：

DisplayRegistry  : DisplayId -> DisplayInfo
SharedGroupRegistry : SharedGroupId -> SharedGroupInfo
SessionRegistry  : SessionId -> SessionInfo
SharedObjectRegistry : { SharedGroupId, ObjectKind, GLname } -> BackendHandle
PrivateObjectRegistry : { SessionId, ObjectKind, name/slot } -> BackendHandle

Backend 不再持有 frontend SharedPtr<T>：只接收 BackendHandle 并通过 BackendHost 查询信息。Frontend 对象销毁时调用 BackendVTable::OnObjectDestroyed 显式通知。

5. Generation 机制

frontend 现状	BFA 字段
GetShapeVersion / GetContentVersion / GetTextureParamsVersion	TextureInfo.generation / contentGeneration / paramsGeneration
GetTextureBindGeneration / GetSamplingResolutionGeneration	TextureInfo.bindGeneration / samplingGeneration
GetRenderStateParametersVersion / GetPipelineStateVersion	RenderState.version / pipelineVersion
GetLinkVersion / GetBackendStateVersion / GetUniformWriteSetVersion / GetUBOContentVersion / GetBlockBindingVersion	ProgramInfo.*Generation
GetConfigVersion / GetAttributeVersion	VertexArrayInfo.generation / attribs[].generation
GetObjectVersion / GetAllFramebufferAttachmentVersions	FramebufferInfo.generation
SamplerObject::GetVersion	SamplerInfo.generation
GetTransformFeedbackGeneration	TransformFeedbackInfo.generation
GetTextureContextId	SessionId 来源

Backend 缓存 key：

{ SharedGroupId, ObjectHandle, objectGeneration }

约定：

• Generation 只在 FullServer 修改（单调递增，不回绕）；
• Backend 只比较、不推导；
• generation 变了就整级/整对象重传，v1 不做 dirty-rect 增量。

6. 跨层数据通路（只读快照，调用期有效）

数据	Host 接口	生命周期
Buffer shadow	GetBufferShadow	调用期有效，Backend 必须 copy
Buffer range	ReadBufferRange	同步拷贝
Texture mip	GetTextureMipInfo + GetTextureMipData	同步拷贝
Program 模块	GetProgramModules	返回的 SPIR-V 指针调用期有效
Persistent map	BufferAcquirePersistentMap	Backend 管理的 GPU 映射

7. 线程模型

• 同一 (sessionId, clientThreadId) 流严格 FIFO；
• 同一 session 的 backend 调用串行；
• 不同 session/thread 可并发，Host 查询线程安全；
• v1 禁止 backend 自建线程回调 Host。

8. C ABI 类型映射

语义	C 类型
DisplayId	uint64_t
SharedGroupId	uint64_t
SessionId	uint64_t
BackendHandle	uint64_t
Generation	uint64_t
Bool	bool（stdbool.h）
Size	uint64_t
错误码	int32_t + Host RecordError

所有 BFA / RuntimeApi 契约头不包含任何 C++ 类型。