Skip to main content

CodecStrategy

Enum CodecStrategy 

Source
#[non_exhaustive]
pub enum CodecStrategy { Unrolled, Table, }
Expand description

How a message’s binary Message implementation is generated. Select it with CodeGenConfig::codec_strategy and CodeGenConfig::codec_strategy_in.

The strategy changes only the code that sizes, writes and decodes a message in the binary wire format. It never changes the wire format, and JSON, text, view and reflection code are generated the same way under either.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

Unrolled

Emit code specialised to each message: the fastest code, and the largest. The default.

§

Table

Emit one static table per message and forward Message to interpreters shared by every message, in the buffa crate. On a large schema it makes the compiled code about 40% smaller at opt-level = "z"; a message that cannot use it keeps its size. It costs run time on messages made of many small fields. The guide’s “Smaller generated code” section has the measurements.

Not every message can use it. These stay Unrolled:

  • a message with a group field;
  • the message type of a group field;
  • a message that uses the MessageSet wire format;
  • a message with extension ranges, when JSON code is generated and unknown fields are preserved;
  • a message with a map field, when map_entries_omit_defaults is set: the table writes both fields of every entry;
  • a message with a field of a non-default string, bytes, or collection type, such as use_bytes_type, string_type, bytes_type, repeated_type, and a custom map_type select. HashMap and BTreeMap maps are supported; a map whose keys or values are of a non-default string or bytes type is not;
  • a message that holds, in a singular, repeated, oneof, or map value field, a message of the same run that has a bytes field of a non-default type, or that holds one. The table decodes from one contiguous slice, so it would copy bytes::Bytes fields that unrolled code decoding from a Bytes shares with the input.

A table message may hold any other message, including as a member of a oneof and as a map value. It reaches a child that is a table message through the child’s table, and any other child, whether it is Unrolled, generated by another crate, or a well-known type, through the child’s Message impl, which costs a function call per child. Selecting a message does not select the messages it holds, and keeping a child Unrolled does not keep the messages that hold it unrolled: to keep a whole path specialised, set its holders to Unrolled too.

A table message differs from an unrolled one in these ways. A field that declares a length past the end of its enclosing message fails at once with DecodeError::UnexpectedEof, where unrolled code can report a different error for the same rejected input; a child reached through its Message impl is read from the slice of the nearest enclosing table message, so it is bounded there. clear() resets the message to its default, which releases the capacity of its strings, vectors and maps, where unrolled code keeps it. Decoding gathers a Buf that is not contiguous into one buffer first. Encoding into any sink other than the cursor that Message::encode and its siblings write a BufMut through, meaning a Rope, a sink defined outside buffa, or a BufMut passed straight to Message::write_to, stages each child reached through its Message impl in a scratch buffer, and a Rope copies it again and cannot share the bytes fields inside it by reference count. Codegen cannot see the fields of a message from another crate, so a table message that holds one with a bytes field of a non-default type copies it on decode. The well-known type google.protobuf.Any is one, because its value is bytes::Bytes. To keep the payload shared with a Bytes input, set the holder to Unrolled with codec_strategy_in.

A message that another crate or codegen run uses as the type of a group or editions DELIMITED field must not be selected, because Message::merge_field on a table message cannot gather a non-contiguous buffer, and the default group decoding calls it. Codegen sees only the group fields of its own run.

Codegen reports the messages that fall back in one CodeGenWarning::TableCodecFallbackSummary. The table code needs Rust 1.77 or later, and contains unsafe code inside buffa macros, so it compiles under #![forbid(unsafe_code)].

Trait Implementations§

Source§

impl Clone for CodecStrategy

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Copy for CodecStrategy

Source§

impl Debug for CodecStrategy

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for CodecStrategy

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl Eq for CodecStrategy

Source§

impl Hash for CodecStrategy

Source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given Hasher. Read more
Source§

impl PartialEq for CodecStrategy

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for CodecStrategy

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.