Struct Packet 

pub struct Packet { /* private fields */ }

Implementations

impl Packet

pub fn empty() -> Self

空包:只带时间戳,用于时间戳边界推进与关流。

pub fn new<T: Any + Send + Sync>(value: T) -> Self

A Rust-native value.

The resulting type_id is NONE, so this packet cannot satisfy a typed port contract — including a C++ kernel’s InputSet<T>() / InputSetBuiltin(...). Sending one into a typed port fails loudly at the first packet rather than silently mismatching, but it fails at runtime, so prefer the right constructor up front:

• a built-in payload → Packet::from_i64, from_f64, from_builtin and friends; these carry the proper type_id and are what cross-language kernels exchange (see ADR #9);
• a custom type that a C++ kernel must read by type → implement InteropType and use Packet::from_interop. The low-level escape hatch is unsafe Packet::new_interop.

Packet::new is still the right choice for a payload that never leaves Rust, or for ports that declare no type (the default).

The type_id is deliberately not derived from Rust’s std::any::TypeId: that is a different identity space from the C++ mangled-name hash, so auto-deriving it would produce ids that look cross-language but only agree with themselves — a silent mismatch, which is strictly worse than the current loud one.

pub fn from_interop<T: InteropType>(value: T) -> Self

A value whose cross-language representation is declared by InteropType.

pub unsafe fn new_interop<T: Any + Send + Sync>(value: T, type_id: u64) -> Self

A Rust-native value carrying an explicit cross-language type_id.

The id must match what the other side expects — typically fnv1a_type_id of the string a C++ kernel declared with LMFLOW_DECLARE_TYPE_NAME. The payload is held in the Foreign form, which gives the C side a readable pointer plus that id.

Built-in ids (0..=15) are rejected: their layouts are owned by the engine and must be constructed with Packet::from_builtin or the corresponding from_* helper.

Safety

T must have exactly the ABI layout associated with type_id in every foreign reader. In particular, do not assign an id for a different type merely to satisfy a port contract.

pub fn from_i64(v: i64) -> Self

内建类型的便捷构造 —— 跨语言稳定,C++/Python 算子都能按类型读取。

pub fn from_f64(v: f64) -> Self

pub fn from_bool(v: bool) -> Self

pub fn from_bytes(v: Vec<u8>) -> Self

pub fn from_string(v: &str) -> Self

命名为 from_string 而非 from_str:后者会与标准库的 FromStr::from_str 混淆(clippy 会拦)。

pub fn as_i64(&self) -> Option<i64>

读取内建整数;非整数包返回 None。

pub fn as_f64(&self) -> Option<f64>

pub fn as_str(&self) -> Option<&str>

pub fn from_builtin(b: Builtin) -> Self

pub unsafe fn from_foreign( ptr: *mut c_void, type_id: u64, drop_fn: Option<unsafe extern "C" fn(*mut c_void)>, ) -> Self

接管外部构造的 payload(C ABI 的 owner==NULL 形态)。

Safety

ptr 必须有效,且 drop_fn 对它恰好可调用一次。

pub fn at(self, ts: Timestamp) -> Self

pub fn set_timestamp(&mut self, ts: Timestamp)

pub fn timestamp(&self) -> Timestamp

pub fn is_empty(&self) -> bool

pub fn type_id(&self) -> u64

pub fn byte_size(&self) -> u64

pub fn payload(&self) -> Option<&Payload>

pub fn ref_count(&self) -> usize

当前引用数(CoW 判定与测试用)。

pub fn get<T: Any>(&self) -> Option<&T>

取 Rust 原生值的引用;类型不符或非 Native 返回 None。

pub fn foreign_ptr(&self) -> Option<*const c_void>

外部(C/C++)payload 的数据指针 —— 供 Rust 宿主读取 C++ 算子产出的包。

调用方须自行确认类型(比对 Packet::type_id 与 fnv1a_type_id), 并保证读取期间本 Packet 存活。

pub fn as_builtin(&self) -> Option<&Builtin>

pub fn metadata(&self) -> &Metadata

pub fn metadata_value(&self, key: &str) -> Option<&MetadataValue>

pub fn has_metadata(&self, key: &str) -> bool

pub fn metadata_keys(&self) -> impl Iterator<Item = &str>

pub fn with_metadata<V: Into<MetadataValue>>( self, key: impl Into<String>, value: V, ) -> Self

pub fn set_metadata<V: Into<MetadataValue>>( &mut self, key: impl Into<String>, value: V, )

pub fn remove_metadata(&mut self, key: &str) -> Option<MetadataValue>

pub fn make_mutable_builtin(&mut self) -> Result<&mut Builtin>

写时复制:取得独占可写的内建 payload。

独占(引用数 1)→ 原地返回,零拷贝;被共享 → 复制一份后返回副本的可写引用。 仅支持 Builtin payload；adopt 的外部 Buffer 走专用 make_mutable_buffer。

pub fn debug_string(&self) -> String

供诊断日志使用的可读描述。

Trait Implementations

impl Clone for Packet

fn clone(&self) -> Packet

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Packet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Packet

fn default() -> Packet

Returns the “default value” for a type.