payloadZBytes property
The payload as a retained ZBytes handle, or null when this sample's carrier did not opt in.
Opt in with retainPayload: true at declaration. It is off by
default, so nothing pays for retention that did not ask for it.
Where payloadBytes is a copy taken as the sample crossed the seam,
this is an owned handle on the payload itself — a shallow, refcounted
clone of what the network delivered. That is what makes two things
expressible that a copy cannot: republishing the payload without copying
it, and asking what backs it (isShmBacked).
Lifetime — and it is YOURS
The handle outlives the delivery callback, the subscriber and the session it arrived on: it is an independent clone, not a view into something the carrier owns. Releasing any of them does not invalidate it.
⛔ Release it. Either ZBytes.dispose it, or hand it to a send that
consumes it (putBytes marks it consumed and frees it). A ZBytes
carries a NativeFinalizer safety net, so a dropped handle is reclaimed
when it is collected — but a finalizer runs at an unpredictable time, or
not at all if the program exits first. The net is not a substitute for
releasing it.
⚠️ Because this holds a native handle, a Sample carrying one cannot
cross an isolate boundary — the VM refuses it, naming ZBytes. A sample
whose payloadZBytes is null still sends normally.
Implementation
final ZBytes? payloadZBytes;