Trait timely_container::ContainerBuilder

pub trait ContainerBuilder: Default + 'static {
    type Container: Container;

    // Required methods
    fn extract(&mut self) -> Option<&mut Self::Container>;
    fn finish(&mut self) -> Option<&mut Self::Container>;
}

A type that can build containers from items.

An implementation needs to absorb elements, and later reveal equivalent information chunked into individual containers, but is free to change the data representation to better fit the properties of the container.

Types implementing this trait should provide appropriate PushInto implementations such that users can push the expected item types.

The owner extracts data in two ways. The opportunistic Self::extract method returns any ready data, but doesn’t need to produce partial outputs. In contrast, Self::finish needs to produce all outputs, even partial ones. Caller should repeatedly call the functions to drain pending or finished data.

The caller should consume the containers returned by Self::extract and Self::finish. Implementations can recycle buffers, but should ensure that they clear any remaining elements.

For example, a consolidating builder can aggregate differences in-place, but it has to ensure that it preserves the intended information.

The trait does not prescribe any specific ordering guarantees, and each implementation can decide to represent a push order for extract and finish, or not.

Required Associated Types

type Container: Container

The container type we’re building.

Required Methods

fn extract(&mut self) -> Option<&mut Self::Container>

Extract assembled containers, potentially leaving unfinished data behind. Can be called repeatedly, for example while the caller can send data.

Returns a Some if there is data ready to be shipped, and None otherwise.

fn finish(&mut self) -> Option<&mut Self::Container>

Extract assembled containers and any unfinished data. Should be called repeatedly until it returns None.

Object Safety

This trait is not object safe.

Implementors

impl<C: Container> ContainerBuilder for CapacityContainerBuilder<C>

type Container = C