Crate protobuf

Expand description

§Library to read and write protocol buffers data

§Version 2 is stable

Currently developed branch of rust-protobuf is 3. It has the same spirit as version 2, but contains numerous improvements like:

runtime reflection for mutability, not just for access
protobuf text format and JSON parsing (which rely on reflection)
dynamic message support: work with protobuf data without generating code from schema

Stable version of rust-protobuf will be supported until version 3 released.

Tracking issue for version 3.

§How to generate rust code

There are several ways to generate rust code from .proto files

§Invoke `protoc` programmatically with protoc-rust crate (recommended)

Have a look at readme in protoc-rust crate.

§Use pure rust protobuf parser and code generator

Readme should be in protobuf-codegen-pure crate.

§Use protoc-gen-rust plugin

Readme is here.

§Generated code

Have a look at generated files (for current development version), used internally in rust-protobuf:

descriptor.rs for descriptor.proto (that is part of Google protobuf)

§Copy on write

Rust-protobuf can be used with bytes crate.

To enable Bytes you need to:

Enable with-bytes feature in rust-protobuf:

[dependencies]
protobuf = { version = "~2.0", features = ["with-bytes"] }

Enable bytes option

with Customize when codegen is invoked programmatically:

protoc_rust::run(protoc_rust::Args {
    ...
    customize: Customize {
        carllerche_bytes_for_bytes: Some(true),
        carllerche_bytes_for_string: Some(true),
        ..Default::default()
    },
});

or in .proto file:

import "rustproto.proto";

option (rustproto.carllerche_bytes_for_bytes_all) = true;
option (rustproto.carllerche_bytes_for_string_all) = true;

With these options enabled, fields of type bytes or string are generated as Bytes or Chars respectively. When CodedInputStream is constructed from Bytes object, fields of these types get subslices of original Bytes object, instead of being allocated on heap.

§Accompanying crates

protoc-rust and protobuf-codegen-pure can be used to rust code from .proto crates.
protobuf-codegen for protoc-gen-rust protoc plugin.
protoc crate can be used to invoke protoc programmatically.
protoc-bin-vendored contains protoc command packed into the crate.

Re-exports§

pub use crate::error::ProtobufError;
pub use crate::error::ProtobufResult;

Modules§

descriptor: Generated file from google/protobuf/descriptor.proto
error: Protobuf error type
ext: Utilities to support “extension” fields.
json: JSON serialization and deserialization.
lazy: Lazily initialized data. Used in generated code.
plugin: Generated file from google/protobuf/compiler/plugin.proto
reflect: Reflection implementation for protobuf types.
rt: Functions used by generated protobuf code. Should not be used by programs written by hands.
rustproto: Generated file from rustproto.proto
text_format: Protobuf “text format” implementation.
types: Implementations of ProtobufType for all types.
well_known_types: Generated code for “well known types”
wire_format: Serialization constants.

Structs§

CachedSize: Cached size field used in generated code. It is always equal to itself to simplify generated code. (Generated code can use #[derive(Eq)]).
CodedInputStream: Buffered read with handy utilities.
CodedOutputStream: Buffered write with handy utilities
RepeatedField: Wrapper around vector to avoid deallocations on clear.
SingularField: Like Option<T>, but keeps the actual element on clear.
SingularPtrField: Like Option<Box<T>>, but keeps the actual element on clear.
UnknownFields: Hold “unknown” fields in parsed message.
UnknownFieldsIter: Iterator over UnknownFields
UnknownValues: Field unknown values.
UnknownValuesIter: Iterator over unknown values

Enums§

UnknownValue: Unknown value.
UnknownValueRef: Reference to unknown value.

Constants§

VERSION: protobuf crate version
VERSION_2_28_0: This symbol can be referenced to assert that proper version of crate is used

Traits§

Clear: anything that can be cleared
Message: Trait implemented for all generated structs for protobuf messages.
ProtobufEnum: Trait implemented by all protobuf enum types.

Functions§

parse_from_bytesDeprecated: Parse message from byte array.
parse_from_readerDeprecated: Parse message from reader. Parse stops on EOF or when error encountered.
parse_length_delimited_fromDeprecated: Parse length-delimited message from stream.
parse_length_delimited_from_bytesDeprecated: Parse length-delimited message from bytes.
parse_length_delimited_from_readerDeprecated: Parse length-delimited message from Read.

Crate protobufCopy item path