Module base::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.