Module descriptor_reflection

Provides infrastructure for de/serializing descriptors embedded in Rust data structures.

Example

use serde_json::to_string;
use base::{
    FileSerdeWrapper, FromRawDescriptor, SafeDescriptor, SerializeDescriptors,
    deserialize_with_descriptors,
};
use tempfile::tempfile;

let tmp_f = tempfile().unwrap();

// Uses a simple wrapper to serialize a File because we can't implement Serialize for File.
let data = FileSerdeWrapper(tmp_f);

// Wraps Serialize types to collect side channel descriptors as Serialize is called.
let data_wrapper = SerializeDescriptors::new(&data);

// Use the wrapper with any serializer to serialize data is normal, grabbing descriptors
// as the data structures are serialized by the serializer.
let out_json = serde_json::to_string(&data_wrapper).expect("failed to serialize");

// If data_wrapper contains any side channel descriptor refs
// (it contains tmp_f in this case), we can retrieve the actual descriptors
// from the side channel using into_descriptors().
let out_descriptors = data_wrapper.into_descriptors();

// When sending out_json over some transport, also send out_descriptors.

// For this example, we aren't really transporting data across the process, but we do need to
// convert the descriptor type.
let mut safe_descriptors = out_descriptors
    .iter()
    .map(|&v| unsafe { SafeDescriptor::from_raw_descriptor(v) });
std::mem::forget(data); // Prevent double drop of tmp_f.

// The deserialize_with_descriptors function is used give the descriptor deserializers access
// to side channel descriptors.
let res: FileSerdeWrapper =
    deserialize_with_descriptors(|| serde_json::from_str(&out_json), safe_descriptors)
       .expect("failed to deserialize");

Modules

with_as_descriptor

Module that exports serialize/deserialize functions for use with #[serde(with = "...")] attribute.

with_raw_descriptor

Module that exports serialize/deserialize functions for use with #[serde(with = "...")] attribute. It only works with fields with RawDescriptor type.

Structs

FileSerdeWrapper

A simple wrapper around File that implements Serialize/Deserialize, which is useful when the #[serde(with = "with_as_descriptor")] trait is infeasible, such as for a field with type Option<File>.

SerializeDescriptors

Wrapper for a Serialize value which will capture any descriptors exported by the value when given to an ordinary Serializer.

Constants

DESCRIPTOR_DST 🔒

DESCRIPTOR_SRC 🔒

Functions

deserialize_descriptor

Deserializes a descriptor provided via deserialize_with_descriptors.

deserialize_with_descriptors

Allows the use of any serde deserializer within a closure while providing access to the a set of descriptors for use in deserialize_descriptor.

init_descriptor_dst 🔒

Initializes the thread local storage for descriptor serialization. Fails if it was already initialized without an intervening take_descriptor_dst on this thread.

push_descriptor 🔒

Pushes a descriptor on the thread local destination of descriptors, returning the index in which the descriptor was pushed. Returns Err if the thread local destination was not already initialized.

serialize_descriptor

Serializes a descriptor for later retrieval in a parent SerializeDescriptors struct.

set_descriptor_src 🔒

Sets the thread local storage of descriptors for deserialization. Fails if this was already called without a call to take_descriptor_src on this thread.

take_descriptor 🔒

Takes a descriptor at the given index from the thread local source of descriptors. Returns None if the thread local source was not already initialized.

take_descriptor_dst 🔒

Takes the thread local storage for descriptor serialization. Fails if there wasn’t a prior call to init_descriptor_dst on this thread.

take_descriptor_src 🔒

Takes the thread local storage of descriptors for deserialization. Fails if the storage was already taken or never set with set_descriptor_src.