Derive Macro Protocol

#[derive(Protocol)]
{
    // Attributes available to this derive:
    #[async_proto]
}

Implements the Protocol trait for this type.

The network representation is very simple:

• Attempting to read an enum with no variants errors immediately, without waiting for data to appear on the stream.
• For non-empty enums, the representation starts with the discriminant (a number representing the variant), starting with 0 for the first variant declared and so on.
  • For enums with up to 256 variants, the discriminant is represented as a u8. For enums with 257 to 65536 variants, as a u16, and so on.
• Then follow the Protocol representations of any fields of the struct or variant, in the order declared.

This representation can waste bandwidth for some types, e.g. structs with multiple bool fields. For those, you may want to implement Protocol manually.

Attributes

This macro’s behavior can be modified using attributes. Multiple attributes can be specified as #[async_proto(attr1, attr2, ...)] or #[async_proto(attr1)] #[async_proto(attr2)] .... The following attributes are available:

• #[async_proto(as_string)]: Implements Protocol for this type by converting from and to a string using the FromStr and ToString traits. The FromStr error type must implement Into<ReadErrorKind>.
  • #[async_proto(map_err = ...)]: Removes the requirement for the FromStr error type to implement Into<ReadErrorKind> and instead uses the given expression (which should be an FnOnce(<T as FromStr>::Err) -> ReadErrorKind) to convert the error.
• #[async_proto(attr(...))]: Adds the given attribute(s) to the Protocol implementation. For example, the implementation can be documented using #[async_proto(attr(doc = "..."))]. May be specified multiple times.
• #[async_proto(via = Proxy)]: Implements Protocol for this type (let’s call it T) in terms of another type (Proxy in this case) instead of using the variant- and field-based representation described above. &'a T must implement Into<Proxy> for all 'a, and Proxy must implement Protocol and TryInto<T> with an Error type that implements Into<ReadErrorKind>.
  • #[async_proto(clone)]: Replaces the requirement for &'a T to implement Into<Proxy> with requirements for T to implement Clone and Into<Proxy>.
  • #[async_proto(map_err = ...)]: Removes the requirement for <Proxy as TryInto<T>>::Error to implement Into<ReadErrorKind> and instead uses the given expression (which should be an FnOnce(<Proxy as TryInto<T>>::Error) -> ReadErrorKind) to convert the error.
• #[async_proto(where(...))]: Overrides the bounds for the generated Protocol implementation. The default is to require Protocol + Send + Sync + 'static for each type parameter of this type.

Compile errors

• This macro can’t be used with unions.