Enum spirit_tokio::either::Either

pub enum Either<A, B> {
    A(A),
    B(B),
}

The Either type allows to wrap two similar Fragments and let the user choose which one will be used.

For example, if your server could run both on common TCP and unix domain stream sockets, you could use the Either<TcpListen, UnixListen>. This fragment would then create resources of type Either<TcpListener, UnixListener>.

Many traits are delegated through to one or the other instance inside (in case both implement it). So, the above resource will implement the Accept trait that will accept instances of Either<TcpStream, UnixStream>. These'll in turn implement AsyncRead and AsyncWrite, therefore can be handled uniformly just as connections.

Deserialization

This uses the untagged serde attribute. This means there are no additional configuration options present and the choice is made by trying to first deserialize the A variant and if that fails, trying the B one. Therefore, the inner resource configs need to have some distinct fields. In our example, this would parse as TcpListen:

[[listen]]
port = 1234

While this as an UnixListen:

[[listen]]
path = "/tmp/socket"

If you need different parsing, you can use either a newtype or remote derive.

Other similar types

This is not the only Either type around. Unfortunately, none of the available ones was just right for the use case here, so this crate rolls its own. But it provides From/Into conversions between them, if the corresponding feature on this crate is enabled.

More than two options

This allows only two variants. However, if you need more, it is possible to nest them and form a tree.

Drawbacks

Due to the complexity of implementation, the Fragment is implemented for either only if both variants are Fragments with simple enough Drivers (drivers that don't sub-divide their Fragments). Therefore, Vec<Either<TcpListen, UnixListen>> will work, but Either<Vec<TcpListen>, Vec<UnixListen>> will not.

This is an implementation limitation and may be lifted in the future (PRs are welcome).

Examples

use std::sync::Arc;

use serde::Deserialize;
use spirit::{AnyError, Empty, Pipeline, Spirit};
use spirit::prelude::*;
#[cfg(unix)]
use spirit_tokio::either::Either;
use spirit_tokio::handlers::PerConnection;
use spirit_tokio::net::TcpListen;
#[cfg(unix)]
use spirit_tokio::net::unix::UnixListen;
use tokio::prelude::*;

// If we want to work on systems that don't have unix domain sockets...

#[cfg(unix)]
type Listener = Either<TcpListen, UnixListen>;
#[cfg(not(unix))]
type Listener = TcpListen;

const DEFAULT_CONFIG: &str = r#"
[[listening_socket]]
port = 1235
max-conn = 20
error-sleep = "100ms"
"#;
#[derive(Default, Deserialize)]
struct Config {
    listening_socket: Vec<Listener>,
}

impl Config {
    fn listen(&self) -> Vec<Listener> {
        self.listening_socket.clone()
    }
}

async fn handle_connection<C: AsyncWrite + Unpin>(mut conn: C) -> Result<(), AnyError> {
    conn.write_all(b"hello world").await?;
    conn.shutdown().await?;
    Ok(())
}

fn main() {
    let handler = PerConnection(|conn, _cfg: &_| async {
        if let Err(e) = handle_connection(conn).await {
            eprintln!("Error: {}", e);
        }
    });
    Spirit::<Empty, Config>::new()
        .config_defaults(DEFAULT_CONFIG)
        .with(Pipeline::new("listen").extract_cfg(Config::listen).transform(handler))
        .run(|spirit| {
            Ok(())
        });
}

Variants

A(A)

B(B)

Implementations

impl<T> Either<T, T>

pub fn into_inner(self) -> T

Extracts the inner value in case both have the same type.

Sometimes, a series of operations produces an Either with both types the same. In such case, Either plays no role anymore and this method can be used to get to the inner value.

Trait Implementations

impl<A, B> Accept for Either<A, B> where
    A: Accept,
    B: Accept, 

type Connection = Either<A::Connection, B::Connection>

The type of the accepted connection.

fn poll_accept(
    &mut self,
    ctx: &mut Context<'_>
) -> Poll<Result<Self::Connection, IoError>>

Poll for availability of the next connection.

fn accept(&mut self) -> AcceptFuture<'_, Self>

Accept the next connection.

impl<A, B> AsyncBufRead for Either<A, B> where
    A: AsyncBufRead + Unpin,
    B: AsyncBufRead + Unpin, 

fn poll_fill_buf(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>
) -> Poll<Result<&[u8], IoError>>

Attempts to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl<A, B> AsyncRead for Either<A, B> where
    A: AsyncRead + Unpin,
    B: AsyncRead + Unpin, 

fn poll_read(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &mut [u8]
) -> Poll<Result<usize, IoError>>

Attempts to read from the AsyncRead into buf.

fn poll_read_buf<Bu: BufMut>(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &mut Bu
) -> Poll<Result<usize, IoError>> where
    Self: Sized, 

Pulls some bytes from this source into the specified BufMut, returning how many bytes were read.

unsafe fn prepare_uninitialized_buffer(
    &self,
    buf: &mut [MaybeUninit<u8>]
) -> bool

Prepares an uninitialized buffer to be safe to pass to read. Returns true if the supplied buffer was zeroed out.

impl<A, B> AsyncSeek for Either<A, B> where
    A: AsyncSeek + Unpin,
    B: AsyncSeek + Unpin, 

fn start_seek(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    position: SeekFrom
) -> Poll<Result<(), IoError>>

Attempts to seek to an offset, in bytes, in a stream.

fn poll_complete(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>
) -> Poll<Result<u64, IoError>>

Waits for a seek operation to complete.

impl<A, B> AsyncWrite for Either<A, B> where
    A: AsyncWrite + Unpin,
    B: AsyncWrite + Unpin, 

fn poll_write(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &[u8]
) -> Poll<Result<usize, IoError>>

Attempt to write bytes from buf into the object.

fn poll_flush(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>
) -> Poll<Result<(), IoError>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>
) -> Poll<Result<(), IoError>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_buf<BU: Buf>(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>,
    buf: &mut BU
) -> Poll<Result<usize, IoError>> where
    Self: Sized, 

Writes a Buf into this value, returning how many bytes were written.

impl<A: Clone, B: Clone> Clone for Either<A, B>

fn clone(&self) -> Either<A, B>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A, B, AR, BR> Comparable<Either<AR, BR>> for Either<A, B> where
    A: Comparable<AR>,
    B: Comparable<BR>, 

fn compare(&self, rhs: &Either<AR, BR>) -> Comparison

Compares two fragments.

impl<A: Copy, B: Copy> Copy for Either<A, B>

impl<A: Debug, B: Debug> Debug for Either<A, B>

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

Formats the value using the given formatter.

impl<'de, A, B> Deserialize<'de> for Either<A, B> where
    A: Deserialize<'de>,
    B: Deserialize<'de>, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<A, B> Driver<Either<A, B>> for EitherDriver<A, B> where
    A: Fragment,
    A::Driver: Driver<A, SubFragment = A> + Default,
    B: Fragment,
    B::Driver: Driver<B, SubFragment = B> + Default, 

type SubFragment = Either<A, B>

The smaller Fragment the driver cuts F into.

fn instructions<T, I>(
    &mut self,
    fragment: &Either<A, B>,
    transform: &mut T,
    name: &'static str
) -> Result<Vec<Instruction<T::OutputResource>>, Vec<AnyError>> where
    T: Transformation<<Self::SubFragment as Fragment>::Resource, I, Self::SubFragment>, 

Issues the instructions how to transition to the new fragment.

fn confirm(&mut self, name: &'static str)

Call to this method informs the Driver that the instructions returned by the last call to instructions were followed and the changes have taken place.

fn abort(&mut self, name: &'static str)

Call to this method informs the Driver that the instructions returned by the last call to instructions were not followed and were dropped.

fn maybe_cached(&self, fragment: &Either<A, B>, name: &'static str) -> bool

Informs if there's a chance the new fragment will use something in the Driver's cache if applied.

impl<A: Eq, B: Eq> Eq for Either<A, B>

impl<A, B> Fragment for Either<A, B> where
    A: Fragment,
    A::Driver: Driver<A, SubFragment = A>,
    B: Fragment,
    B::Driver: Driver<B, SubFragment = B>, 

type Driver = EitherDriver<A, B>

The default driver to be used by the fragment.

type Installer = EitherInstaller<A::Installer, B::Installer>

The default installer to be used unless a transformation or the user doesn't provide one.

type Seed = Either<A::Seed, B::Seed>

The intermediate product if the fragment supports two-stage creation of Resources. If not, it can be set to ().

type Resource = Either<A::Resource, B::Resource>

The actual product this Fragment creates.

fn make_seed(&self, name: &'static str) -> Result<Self::Seed, AnyError>

Runs the first stage of creation.

fn make_resource(
    &self,
    seed: &mut Self::Seed,
    name: &'static str
) -> Result<Self::Resource, AnyError>

Runs the second stage of creation.

const RUN_BEFORE_CONFIG: bool

Configuration if the pipeline should be run once even before the config is loaded.

fn create(
    &self,
    name: &'static str
) -> Result<Self::Resource, Box<dyn Error + 'static + Sync + Send>>

Runs both stages of creation at once.

fn init<B>(
    builder: B,
    &'static str
) -> Result<B, Box<dyn Error + 'static + Sync + Send>> where
    B: Extensible<Ok = B>,
    <B as Extensible>::Config: DeserializeOwned,
    <B as Extensible>::Config: Send,
    <B as Extensible>::Config: Sync,
    <B as Extensible>::Config: 'static,
    <B as Extensible>::Opts: StructOpt,
    <B as Extensible>::Opts: Send,
    <B as Extensible>::Opts: Sync,
    <B as Extensible>::Opts: 'static, 

An initialization routine.

impl<A, B> From<Either<A, B>> for Either<A, B>

fn from(e: FutEither<A, B>) -> Self

Performs the conversion.

impl<A, B> From<Either<A, B>> for Either<A, B>

fn from(e: OtherEither<A, B>) -> Self

Performs the conversion.

impl<A, B> Future for Either<A, B> where
    A: Future + Unpin,
    B: Future + Unpin, 

type Output = Either<A::Output, B::Output>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<A: Hash, B: Hash> Hash for Either<A, B>

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<A, B, RA, RB, O, C> Installer<Either<RA, RB>, O, C> for EitherInstaller<A, B> where
    A: Installer<RA, O, C>,
    B: Installer<RB, O, C>, 

type UninstallHandle = Either<A::UninstallHandle, B::UninstallHandle>

A handle representing lifetime of the resource.

fn install(
    &mut self,
    resource: Either<RA, RB>,
    name: &'static str
) -> Self::UninstallHandle

Installs another instance of the resource.

fn init<E: Extensible<Opts = O, Config = C, Ok = E>>(
    &mut self,
    builder: E,
    name: &'static str
) -> Result<E, AnyError> where
    E::Config: DeserializeOwned + Send + Sync + 'static,
    E::Opts: StructOpt + Send + Sync + 'static, 

Initialize the installer.

impl<A, B> Into<Either<A, B>> for Either<A, B>

fn into(self) -> FutEither<A, B>

Performs the conversion.

impl<A, B> Into<Either<A, B>> for Either<A, B>

fn into(self) -> OtherEither<A, B>

Performs the conversion.

impl<A: Ord, B: Ord> Ord for Either<A, B>

fn cmp(&self, other: &Either<A, B>) -> Ordering

This method returns an Ordering between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl<A: PartialEq, B: PartialEq> PartialEq<Either<A, B>> for Either<A, B>

fn eq(&self, other: &Either<A, B>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Either<A, B>) -> bool

This method tests for !=.

impl<A: PartialOrd, B: PartialOrd> PartialOrd<Either<A, B>> for Either<A, B>

fn partial_cmp(&self, other: &Either<A, B>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Either<A, B>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Either<A, B>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Either<A, B>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Either<A, B>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A, B> Serialize for Either<A, B> where
    A: Serialize,
    B: Serialize, 

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl<A, B> Stackable for Either<A, B> where
    A: Stackable,
    B: Stackable, 

impl<A, B> Stream for Either<A, B> where
    A: Stream + Unpin,
    B: Stream + Unpin, 

type Item = Either<A::Item, B::Item>

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut Self>,
    ctx: &mut Context<'_>
) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<A, B> StructDoc for Either<A, B> where
    A: StructDoc,
    B: StructDoc, 

fn document() -> Documentation

Returns the documentation for the type.

impl<A, B> StructuralEq for Either<A, B>

impl<A, B> StructuralPartialEq for Either<A, B>