Enum mozjs::jsapi::StructuredCloneScope

#[repr(u32)]
pub enum StructuredCloneScope {
    SameProcess = 1,
    DifferentProcess = 2,
    DifferentProcessForIndexedDB = 3,
    Unassigned = 4,
    UnknownDestination = 5,
}

Indicates the “scope of validity” of serialized data.

Writing plain JS data produces an array of bytes that can be copied and read in another process or whatever. The serialized data is Plain Old Data. However, HTML also supports Transferable objects, which, when cloned, can be moved from the source object into the clone, like when you take a photograph of someone and it steals their soul. See https://developer.mozilla.org/en-US/docs/Web/API/Transferable. We support cloning and transferring objects of many types.

For example, when we transfer an ArrayBuffer (within a process), we “detach” the ArrayBuffer, embed the raw buffer pointer in the serialized data, and later install it in a new ArrayBuffer in the destination realm. Ownership of that buffer memory is transferred from the original ArrayBuffer to the serialized data and then to the clone.

This only makes sense within a single address space. When we transfer an ArrayBuffer to another process, the contents of the buffer must be copied into the serialized data. (The original ArrayBuffer is still detached, though, for consistency; in some cases the caller shouldn’t know or care if the recipient is in the same process.)

ArrayBuffers are actually a lucky case; some objects (like MessagePorts) can’t reasonably be stored by value in serialized data – it’s pointers or nothing.

So there is a tradeoff between scope of validity – how far away the serialized data may be sent and still make sense – and efficiency or features. The read and write algorithms therefore take an argument of this type, allowing the user to control those trade-offs.

Variants

SameProcess = 1

The most restrictive scope, with greatest efficiency and features.

When writing, this means: The caller promises that the serialized data will not be shipped off to a different process or stored in a database. However, it may be shipped to another thread. It’s OK to produce serialized data that contains pointers to data that is safe to send across threads, such as array buffers. In Rust terms, the serialized data will be treated as Send but not Copy.

When reading, this means: Accept transferred objects and buffers (pointers). The caller promises that the serialized data was written using this API (otherwise, the serialized data may contain bogus pointers, leading to undefined behavior).

Starts from 1 because there used to be a SameProcessSameThread enum value of 0 and these values are encoded into the structured serialization format as part of the SCTAG_HEADER, and IndexedDB persists the representation to disk.

DifferentProcess = 2

When writing, this means we’re writing for an audience in a different process. Produce serialized data that can be sent to other processes, bitwise copied, or even stored as bytes in a database and read by later versions of Firefox years from now. The HTML5 spec refers to this as “ForStorage” as in StructuredSerializeForStorage, though we use DifferentProcess for IPC as well as storage.

Transferable objects are limited to ArrayBuffers, whose contents are copied into the serialized data (rather than just writing a pointer).

When reading, this means: Do not accept pointers.

DifferentProcessForIndexedDB = 3

Handle a backwards-compatibility case with IndexedDB (bug 1434308): when reading, this means to treat legacy SameProcess data as if it were DifferentProcess.

Do not use this for writing; use DifferentProcess instead.

Unassigned = 4

Existing code wants to be able to create an uninitialized JSStructuredCloneData without knowing the scope, then populate it with data (at which point the scope is known.)

UnknownDestination = 5

This scope is used when the deserialization context is unknown. When writing, DifferentProcess or SameProcess scope is chosen based on the nature of the object.

Trait Implementations

impl Clone for StructuredCloneScope

fn clone(&self) -> StructuredCloneScope

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for StructuredCloneScope

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

Formats the value using the given formatter.

impl Hash for StructuredCloneScope

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for StructuredCloneScope

fn eq(&self, other: &StructuredCloneScope) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for StructuredCloneScope

impl Eq for StructuredCloneScope

impl StructuralPartialEq for StructuredCloneScope