GFProtocolAckLedger¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/io/gf_protocol_ack_ledger.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：运行时句柄 (
runtime_handle) - 首次版本：
7.0.0
通用协议确认账本。 记录任意协议的待确认 packet/request ID、确认结果、失败和过期状态。 它不实现具体网络协议，也不规定 ID 生成、重传策略或连接生命周期。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | STATE_PENDING |
const STATE_PENDING: StringName = &"pending" |
| 常量 | STATE_ACKED |
const STATE_ACKED: StringName = &"acked" |
| 常量 | STATE_FAILED |
const STATE_FAILED: StringName = &"failed" |
| 常量 | STATE_EXPIRED |
const STATE_EXPIRED: StringName = &"expired" |
| 属性 | timeout_msec |
var timeout_msec: int = 0: |
| 属性 | max_entries |
var max_entries: int = 256 |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | clear |
func clear() -> void: |
| 方法 | register_packet |
func register_packet(packet_id: Variant, entry_metadata: Dictionary = {}, now_msec: int = -1) -> bool: |
| 方法 | acknowledge_packet |
func acknowledge_packet(packet_id: Variant, result: Variant = null, now_msec: int = -1) -> bool: |
| 方法 | fail_packet |
func fail_packet(packet_id: Variant, error: String = "", result: Variant = null, now_msec: int = -1) -> bool: |
| 方法 | expire_pending |
func expire_pending(now_msec: int = -1) -> Dictionary: |
| 方法 | remove_packet |
func remove_packet(packet_id: Variant) -> bool: |
| 方法 | has_packet |
func has_packet(packet_id: Variant) -> bool: |
| 方法 | is_pending |
func is_pending(packet_id: Variant) -> bool: |
| 方法 | get_packet |
func get_packet(packet_id: Variant) -> Dictionary: |
| 方法 | get_packets |
func get_packets(state_filter: StringName = &"") -> Array[Dictionary]: |
| 方法 | get_pending_ids |
func get_pending_ids() -> Array: |
| 方法 | get_count |
func get_count() -> int: |
| 方法 | get_pending_count |
func get_pending_count() -> int: |
| 方法 | get_debug_snapshot |
func get_debug_snapshot() -> Dictionary: |
常量¶
STATE_PENDING¶
- API：
public - 首次版本：
7.0.0
条目等待确认。
STATE_ACKED¶
- API：
public - 首次版本：
7.0.0
条目已经确认。
STATE_FAILED¶
- API：
public - 首次版本：
7.0.0
条目失败。
STATE_EXPIRED¶
- API：
public - 首次版本：
7.0.0
条目等待超时。
属性¶
timeout_msec¶
- API：
public - 首次版本：
7.0.0
新条目的默认等待超时；小于等于 0 时不自动过期。
max_entries¶
- API：
public - 首次版本：
7.0.0
最大记录数量；小于等于 0 时不限制。
metadata¶
- API：
public - 首次版本：
7.0.0
调用方自定义元数据。
结构：
metadata: Dictionary[String, Variant] copied into debug snapshots.
方法¶
clear¶
- API：
public - 首次版本：
7.0.0
清空全部记录。
register_packet¶
- API：
public - 首次版本：
7.0.0
func register_packet(packet_id: Variant, entry_metadata: Dictionary = {}, now_msec: int = -1) -> bool:
注册一个待确认条目。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
entry_metadata |
条目元数据。 |
now_msec |
当前时间；小于 0 时使用 Time.get_ticks_msec()。 |
返回：注册成功返回 true。
结构：
packet_id: Variant used as dictionary key; null and empty text keys are rejected.entry_metadata: Dictionary copied into the ledger entry.
acknowledge_packet¶
- API：
public - 首次版本：
7.0.0
标记条目确认成功。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
result |
确认结果。 |
now_msec |
当前时间；小于 0 时使用 Time.get_ticks_msec()。 |
返回：状态成功变更时返回 true。
结构：
packet_id: Variant stable protocol packet id.result: Variant copied into the ledger entry.
fail_packet¶
- API：
public - 首次版本：
7.0.0
func fail_packet(packet_id: Variant, error: String = "", result: Variant = null, now_msec: int = -1) -> bool:
标记条目失败。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
error |
失败说明。 |
result |
失败结果。 |
now_msec |
当前时间；小于 0 时使用 Time.get_ticks_msec()。 |
返回：状态成功变更时返回 true。
结构：
packet_id: Variant stable protocol packet id.result: Variant copied into the ledger entry.
expire_pending¶
- API：
public - 首次版本：
7.0.0
让超过 deadline 的待确认条目进入 expired 状态。
参数：
| 名称 | 说明 |
|---|---|
now_msec |
当前时间；小于 0 时使用 Time.get_ticks_msec()。 |
返回：过期报告。
结构：
return: Dictionary with expired_count, expired_ids, pending_count, and state_counts.
remove_packet¶
- API：
public - 首次版本：
7.0.0
移除指定条目。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
返回：移除成功返回 true。
结构：
packet_id: Variant stable protocol packet id.
has_packet¶
- API：
public - 首次版本：
7.0.0
检查条目是否存在。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
返回：存在返回 true。
结构：
packet_id: Variant stable protocol packet id.
is_pending¶
- API：
public - 首次版本：
7.0.0
检查条目是否仍待确认。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
返回：待确认返回 true。
结构：
packet_id: Variant stable protocol packet id.
get_packet¶
- API：
public - 首次版本：
7.0.0
获取条目副本。
参数：
| 名称 | 说明 |
|---|---|
packet_id |
协议层稳定 ID。 |
返回：条目副本；不存在时返回空字典。
结构：
packet_id: Variant stable protocol packet id.return: Dictionary with id, state, timestamps, deadline_msec, result, error, and metadata.
get_packets¶
- API：
public - 首次版本：
7.0.0
按状态获取条目副本。
参数：
| 名称 | 说明 |
|---|---|
state_filter |
状态过滤；为空时返回所有条目。 |
返回：条目数组。
结构：
return: Array[Dictionary] of ledger entry copies.
get_pending_ids¶
- API：
public - 首次版本：
7.0.0
获取待确认 ID 列表。
返回：待确认 ID 数组。
结构：
return: Array[Variant] copied from pending ledger entries.
get_count¶
- API：
public - 首次版本：
7.0.0
获取总记录数。
返回：总记录数。
get_pending_count¶
- API：
public - 首次版本：
7.0.0
获取待确认记录数。
返回：待确认记录数。
get_debug_snapshot¶
- API：
public - 首次版本：
7.0.0
获取调试快照。
返回：调试快照。
结构：
return: Dictionary with count, pending_count, state_counts, ids, timeout_msec, max_entries, and metadata.