#[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
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
MessageSetwire format; - a message with extension ranges, when JSON code is generated and unknown fields are preserved;
- a message with a
mapfield, whenmap_entries_omit_defaultsis 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 custommap_typeselect.HashMapandBTreeMapmaps are supported; amapwhose 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 abytesfield of a non-default type, or that holds one. The table decodes from one contiguous slice, so it would copybytes::Bytesfields that unrolled code decoding from aBytesshares 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)].