Struct SerializeDriver 

pub struct SerializeDriver<'a> { /* private fields */ }

The driver allows serializing a Serialize iteratively.

This is the only way to convert from a Serialize into an event stream. There are several ways to receive the events:

• drive invokes a callback for every event and drive_sink delivers them to an EventSink. Both serialize the value at once.
• drive_until delivers the events to an EventSink which can pause the driver, for instance to write the output of large values in pieces.
• next returns one event at a time.

Event sinks can also receive the values of the events to describe them (see EventSink::DESCRIBED).

When the serialization fails, the error gets the context of the current value attached (see State::add_error_context).

Layers

Layers sit between the serialized values and the format and see every event before the format receives it. They are added with push_layer and are not supported by next.

Implementations

impl<'a> SerializeDriver<'a>

pub fn new<T: Serialize>(value: &'a T) -> SerializeDriver<'a>

Creates a new driver which serializes the given value implementing Serialize.

pub fn from_ref(serializable: SerializeRef<'a>) -> SerializeDriver<'a>

Creates a new driver which serializes the value of a reference.

Unlike new this is not generic, the reference can be to a value with an adapter (see SerializeRef::serialize_as).

pub fn state(&self) -> &State

Returns a borrowed reference to the current serializer state.

pub fn state_mut(&mut self) -> &mut State

Returns a mutable reference to the current serializer state.

This can be used to place extension values into the state which the serializable values can then pick up.

pub fn set_context(&mut self, context: Context)

Sets the context of the serialization.

The values of the context are the defaults of the extension values of the state (see Context). This replaces the context of the driver. Formats add the values of their own context for the types it has no value for (see set_default_context).

pub fn set_default_context(&mut self, context: Context)

Adds the values of a context that the context of the driver has no value for.

Formats use this for the context they were given (for instance the one of their configuration). A context that was set on the driver before (for instance in the setup callback of serialize_with) takes precedence: its values are kept and the values of the given context are only added for the types it has no value for.

pub fn context(&self) -> &Context

Returns the context of the serialization.

pub fn push_layer<L: Layer + 'static>(&mut self, layer: L)

Adds a layer.

Layers see the events in the order they were added: the layer that was added first sees the events produced by the values, the last one passes them on to the format. See Layer for more information.

pub fn next( &mut self, ) -> Result<Option<(Event<'_>, SerializeRef<'_>, &mut State)>, Error>

Produces the next serialization event.

Panics

The driver will panic if the data fed from the serializer is malformed. As layers can change the number of events, this method panics if layers were added.

pub fn drive<F>(&mut self, f: F) -> Result<(), Error>

where F: FnMut(Event<'_>, &mut State) -> Result<(), Error>,

Drives the serialization to the end and invokes a callback for every event.

This produces the same events as calling next until it returns None but it’s faster. The first error (either produced by a serializable or returned by the callback) aborts the serialization. To receive the values of the events or to pause the serialization, use an EventSink.

let serializable = vec!["foo", "bar", "baz"];
let mut events = Vec::new();
SerializeDriver::new(&serializable).drive(|event, _state| {
    events.push(event.to_static());
    Ok(())
})?;
assert_eq!(events.len(), 5);

pub fn drive_sink<S: EventSink>(&mut self, sink: &mut S) -> Result<(), Error>

Like drive but delivers the events to an EventSink.

The sink is not asked to pause (see drive_until), the value is serialized at once.

pub fn drive_until<S: EventSink>(&mut self, sink: &mut S) -> Result<bool, Error>

Drives the serialization until it’s complete or the sink pauses it.

Returns true once the serialization is complete. If the sink paused the driver (see EventSink::pause), false is returned and the next call continues where this one stopped. At least one value is serialized per call.

Unlike drive, which emits values that only hold atoms (like a Vec<u64>) at once, the driver emits such values in pieces of a few hundred atoms and can pause in between. The amount of events between two pauses only depends on the size of the atoms, not on the size of the value.

/// Collects events and pauses once it holds 100.
struct Collect(Vec<Event<'static>>);

impl EventSink for Collect {
    fn event(
        &mut self,
        event: Event<'_>,
        _value: SerializeRef<'_>,
        _state: &mut State,
    ) -> Result<(), Error> {
        self.0.push(event.to_static());
        Ok(())
    }

    fn pause(&mut self) -> bool {
        self.0.len() >= 100
    }
}

let value: Vec<u64> = (0..10_000).collect();
let mut driver = SerializeDriver::new(&value);
let mut sink = Collect(Vec::new());
let mut events = 0;
loop {
    let done = driver.drive_until(&mut sink)?;
    // the events so far are processed while the driver is paused
    assert!(sink.0.len() < 1000);
    events += sink.0.len();
    sink.0.clear();
    if done {
        break;
    }
}
assert_eq!(events, 10_002);

Trait Implementations

impl<'a> Drop for SerializeDriver<'a>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.