whichever

Implements a trait for an enum by forwarding to whichever variant it holds.

// In the crate that owns the trait.
#[whichever::dispatchable]
pub trait Shape {
    fn area(&self) -> u32;
    fn name(&self) -> &'static str {
        "shape"
    }
}

// In any crate that owns an enum over implementors.
#[whichever::dispatch(Shape)]
pub enum AnyShape {
    Circle(Circle),
    Square(Square),
}

AnyShape now implements Shape with one match per method, each arm a fully qualified call into the variant's payload, and gets From<Circle> and From<Square>:

impl Shape for AnyShape {
    #[inline]
    fn area(&self) -> u32 {
        match self {
            AnyShape::Circle(inner) => <Circle as Shape>::area(inner),
            AnyShape::Square(inner) => <Square as Shape>::area(inner),
        }
    }
    #[inline]
    fn name(&self) -> &'static str {
        match self {
            AnyShape::Circle(inner) => <Circle as Shape>::name(inner),
            AnyShape::Square(inner) => <Square as Shape>::name(inner),
        }
    }
}

That is the code a careful hand would write: no trait object, no closure, no conversion, and a variant's override of a default method is never hidden by the default.

Documentation

• This file: what the attributes generate, every option, and the limits. The API reference is on docs.rs.
• When enum dispatch pays: choosing between an enum, a trait object and a generic, with the measurements behind each piece of advice.
• Benchmarks: what is compared with what, how, and how to run it; results from the last run.

Why another one

An enum over the implementors of a trait is the cheapest way to hold "one of these": no allocation, no vtable, and the compiler sees every arm. The forwarding impl is the price, paid again for every method and every variant.

enum_dispatch made it automatic, but it keeps the trait's definition in a process-global cache inside the proc-macro server. That is why it cannot see a trait from another crate (the enum compiles with no impl and the first call fails), panics on associated types and receiver-less methods, and loses the spans of its errors. whichever keeps nothing between expansions: #[dispatchable] exports a hidden macro carrying the trait's tokens, re-exported under the trait's own name, and #[dispatch] calls it. The trait and the enum may live in different crates, in any order, and the shapes real traits have (associated types, &Self arguments, generic traits, several traits on one enum) dispatch too.

Probed on 2026-11-01 against the versions shown, with the trait in one crate and the enum in another, on stable Rust. A dash means the case was not probed for that crate. The whichever column is what tests/ checks.

Performance

The match the attribute writes is the one a careful hand writes, and so is the machine code. benchmarks/ compares whichever with a hand-written impl, with Box<dyn Trait> and with the enums of enum_dispatch, ambassador, enum_delegate, delegation and delegate, calling from a crate other than the enum's, without LTO, over collections of 2 to 32 variants in uniform, cyclic and random layouts, with method bodies the optimiser can inline and bodies it cannot. From the last run, on an Apple M1 Pro (full tables):

• whichever is within 1.4% of the hand-written match in every cell of the main matrix, two families by three layouts by five variant counts, and the functions it generates are identical to the hand-written ones instruction for instruction.
• Over a random 8-variant collection, one &self call costs 1.7 ns per element against 2.3 ns through a Box<dyn Trait> when the method bodies can be inlined, and 2.1 ns against 2.3 ns when they cannot. Most of the enum's advantage is what the optimiser gets to see, not the dispatch.
• Where the payload's place matters, the gap is wide: 1.7 ns against 8.1 ns per element over 4 Mi scattered elements, and a collection is built 13x faster without a box per element.
• A generated impl without #[inline] (enum_delegate, delegation) pays an extra out-of-line call across the crate boundary, from 15% to 4x depending on the method and the variant count.

Whether an enum is the right choice for a given program, and how to get these numbers out of it, is the subject of docs/when-to-use-enum-dispatch.md.

Options

All options follow the trait path in #[dispatch(..)].

• Name = Type fixes the associated type Name instead of taking it from the first variant. A method returning Self::Name is converted with Into, one returning Result<_, Self::Name> with map_err(Into::into), so variants with their own error types can share one enum:

  #[whichever::dispatch(Storage, Error = StorageError)]
  pub enum AnyStorage {
      Memory(MemoryStorage), // Error = StorageError
      Disk(DiskStorage),     // Error = io::Error, which is Into<StorageError>
  }
  

• Name = value fixes the associated const Name, for a const that differs per payload by design, such as a kind discriminator:

  #[whichever::dispatch(Proof, KIND = "any")]
  pub enum AnyProof {
      Encoding(EncodingProof), // KIND = "encoding"
      Ordering(OrderingProof), // KIND = "ordering"
  }
  

• mismatch(method = expr, ..) gives the result of method when its Self arguments hold a different variant than self. The trait author can decide once instead, with #[dispatch(mismatch = expr)] on the method:

  #[whichever::dispatchable]
  pub trait Shape {
      /// Two different kinds of shape are never congruent.
      #[dispatch(mismatch = false)]
      fn congruent(&self, other: &Self) -> bool;
  }
  

• from = false suppresses the From<Payload> impls.

• try_from = true adds TryFrom<Enum> for Payload for every payload type, with the enum as the error, so a mismatch hands the value back.

Three options go on a variant. #[dispatch(from = false)] leaves the variant out of the From and TryFrom impls, for a payload such as String that should not convert into the enum, and #[dispatch(try_from = true)] adds the TryFrom impl for that payload alone. #[dispatch(deref)] calls the trait on what the payload dereferences to, so Box<T>, Rc<T>, Arc<T>, &T and &mut T payloads dispatch like a plain T:

#[whichever::dispatch(Shape)]
pub enum AnyShape<'a> {
    #[dispatch(deref)]
    Boxed(Box<Circle>),
    #[dispatch(deref)]
    Borrowed(&'a Square),
    Plain(Square),
}

Several traits are dispatched by repeating the attribute; a supertrait is one more attribute:

#[whichever::dispatch(Shape)]
#[whichever::dispatch(Drawable)]
pub enum AnyShape { /* .. */ }

A generic trait is dispatched at a concrete instantiation: #[whichever::dispatch(Encoder<Json>)]. Type, lifetime and const parameters are substituted in every signature, and F::Value becomes <Json as Format>::Value when F has one bound.

Inherent methods

An enum often needs methods of its own that only some variants can answer. #[dispatch] on an inherent impl block forwards each marked method to the named variants' method of the same name; the body is what every other variant returns. * names every variant, and the method then has no body:

#[whichever::dispatch]
impl AnyShape {
    /// Only circles have a radius.
    #[dispatch(Circle, with = Some)]
    pub fn radius(&self) -> Option<f64> {
        None
    }

    #[dispatch(*)]
    pub fn describe(&self) -> String;

    #[dispatch(*, call = describe)]
    pub fn label(&self) -> String;
}

with = path wraps each forwarded result, call = name forwards to a method of another name, async methods and methods returning impl Future are awaited, and methods without the attribute are left alone. A method returning Self, Option<Self> or Result<Self, E> wraps the payload's result back into the variant, as trait dispatch does. With with, the payload returns the plain value and with lifts the wrapped variant: #[dispatch(Circle, with = Some)] on fn grown(&self) -> Option<Self> calls a Circle::grown that returns a Circle. The impl block has to be in the enum's crate, which inherent impls are anyway; a bare #[dispatch] on an enum registers it for this without dispatching a trait.

Traits from std and other crates

#[dispatch] reads a trait's signatures from the hidden macro that #[dispatchable] leaves next to the trait, so a trait from std or from a crate you do not own cannot be dispatched as it is. Restate it once, with remote naming the real trait, and dispatch the restatement:

#[whichever::dispatchable(remote = std::io::Write)]
trait Write {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize>;
    fn flush(&mut self) -> std::io::Result<()>;
    fn write_all(&mut self, buf: &[u8]) -> std::io::Result<()>;
}

#[whichever::dispatch(Write)] // implements std::io::Write
pub enum Stream {
    Tcp(TcpStream),
    #[cfg(unix)]
    Unix(UnixStream),
}

Nothing is emitted for the restatement but the macro, so the name is free for use std::io::Write; in the same module. Exactly the methods restated are forwarded, provided ones included; a changed signature fails to compile against the real trait. The restatements an enum most often needs ship in whichever::foreign: Display, Debug, Error, PartialEq, Iterator, Read, Write, BufRead and Seek, each forwarding every provided method a match can forward. #[dispatch(whichever::foreign::Display)] on an error enum replaces the usual hand-written match, and the variant that holds a String keeps From away with #[dispatch(from = false)]:

#[derive(Debug)]
#[whichever::dispatch(whichever::foreign::Display)]
#[whichever::dispatch(whichever::foreign::Error)]
pub enum ClientError {
    Io(io::Error),
    Parse(ParseIntError),
    #[dispatch(from = false)]
    BadUrl(String),
}

A method the enum answers differently from every payload, such as Error::source returning None for some variants, goes in a partial impl block.

Methods the enum implements itself

A trait method without a receiver, such as a constructor, has no variant to dispatch on, and sometimes the enum's answer to a method differs from every payload's. Put #[dispatch] on a trait impl block holding just those items, and the rest of the trait is forwarded around them:

#[whichever::dispatch]
pub enum Handler {
    Text(TextHandler),
    Map(MapHandler),
}

#[whichever::dispatch]
impl HandlerTrait for Handler {
    fn from_handler(handler: Handler) -> Option<Self> {
        Some(handler)
    }
}

The enum then does not name that trait in its own attribute, since the block is the impl. Options for the trait, Name = Type and mismatch, go on the block's attribute; an associated type written in the block counts as an override too. A method written in the block replaces the forwarding for every variant, provided methods included, which is the way to leave a payload's method out on purpose. The block's own header, generics and bounds included, becomes the impl's header. Like inherent blocks, it has to be in the enum's crate.

Wrapping the enum in a struct

A dispatch enum is often private, behind a public struct that forwards the same trait by hand, and the hand-written half forwards only the required methods, so a payload's override of a provided method never reaches the public type. #[dispatch] on the struct forwards to its one field, or to the field marked #[dispatch], every method included:

#[whichever::dispatch(FlowCtrlHooks)]
enum FlowCtrlInner {
    Window(WindowFlowCtrl),
    XonXoff(XonXoffFlowCtrl),
}

#[whichever::dispatch(FlowCtrlHooks)]
pub struct StreamFlowCtrl {
    #[dispatch]
    inner: FlowCtrlInner,
    hooks: Hooks,
}

The field may be any implementor, not only a dispatch enum, and #[dispatch(deref)] on it reaches through a Box or another pointer. A method returning Self is rebuilt only around a struct with no other field; otherwise it is an error, and the method goes in a partial impl block, which works on a struct like on an enum. A struct gets no From impls. Self arguments need no mismatch: two values of the struct always hold the same field.

What each trait item becomes

Limits

• Every variant a trait is dispatched to holds exactly one unnamed field, Name(Payload), and every payload implements the trait. A variant of another shape is reported under its own #[cfg], so a variant compiled out, such as a test-only mock, is no error; an enum that only forwards inherent methods may hold such variants, which take the method's body.
• Return-position impl Trait cannot be dispatched by a match, except impl Future<Output = T>, which is awaited like an async fn.
• A deref variant cannot take part in a method returning Self: there is no way to put the result back behind the pointer.
• Generic associated types are not supported.
• Receivers are self, &self, &mut self, self: Box<Self> on deref variants holding a Box, and self: Pin<&Self> or self: Pin<&mut Self> when every payload is Unpin. Rc<Self>, Arc<Self> and Pin<Box<Self>> would need a refcount or an allocation, so they are not.
• The types in the trait's signatures are written into the enum's module and must be in scope there, as for a hand-written impl; crate:: paths are rewritten to the trait's crate, super:: and self:: paths are not. They must also be nameable from there: a private alias or type in a signature limits the trait to its own crate.
• An associated const of a type other than an integer, bool, char or &str, or on a generic enum, is taken from the first variant without a check.
• One macro_rules! may emit a #[dispatchable] trait in several modules when at least one token of the trait, its name or a method's, comes from the invocation. A trait written out in full in the macro's body gets the same hidden macro name at every invocation, and rustc reports it as defined multiple times, unless each invocation passes its own #[dispatchable(name = ..)].

Every unsupported shape is reported as one sentence on the offending trait item or variant; see tests/ui for all of them. A rejected enum is still emitted, so the derives, uses and impl blocks around it compile and that one error stands alone.

"cannot find macro Shape in this scope" at the enum means the trait is not marked #[dispatchable], or the trait, which carries the macro, is not imported where the enum is. A std::, core:: or alloc:: path in #[dispatch] is reported directly, with the whichever::foreign declaration or the remote restatement to use instead.

One macro_rules! that emits the same pub trait, written out in full, at two places gets the same hidden macro name twice; #[dispatchable(name = tokio)] names the macro explicitly and tells the two apart.

Compatibility

no_std, with no dependencies beyond the proc-macro crate. The minimum supported Rust version is 1.88. Both the crate that owns the trait and the crate that owns the enum depend on whichever; renaming the dependency is fine.

#[dispatchable] on a pub trait adds one #[doc(hidden)] exported macro to the crate root, named after the trait and the position of its tokens, which is how another crate's enum reaches the trait's signatures. A trait of any other visibility keeps its macro in its own module and adds nothing to the crate root.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.