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.
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
andprotobuf-codegen-pure
can be used to rust code from.proto
crates.protobuf-codegen
forprotoc-gen-rust
protoc plugin.protoc
crate can be used to invokeprotoc
programmatically.protoc-bin-vendored
containsprotoc
command packed into the crate.
Re-exports
pub use crate::error::ProtobufError;
pub use crate::error::ProtobufResult;
Modules
Generated file from google/protobuf/descriptor.proto
Protobuf error type
Utilities to support “extension” fields.
JSON serialization and deserialization.
Lazily initialized data. Used in generated code.
Generated file from google/protobuf/compiler/plugin.proto
Reflection implementation for protobuf types.
Functions used by generated protobuf code. Should not be used by programs written by hands.
Generated file from rustproto.proto
Protobuf “text format” implementation.
Implementations of ProtobufType
for all types.
Generated code for “well known types”
Serialization constants.
Structs
Cached size field used in generated code.
It is always equal to itself to simplify generated code.
(Generated code can use #[derive(Eq)]
).
Thin wrapper around Bytes
which guarantees that bytes are valid UTF-8 string.
Should be API-compatible to String
.
Buffered read with handy utilities.
Buffered write with handy utilities
Wrapper around vector to avoid deallocations on clear.
Like Option<T>
, but keeps the actual element on clear
.
Like Option<Box<T>>
, but keeps the actual element on clear
.
Hold “unknown” fields in parsed message.
Iterator over UnknownFields
Field unknown values.
Iterator over unknown values
Enums
Unknown value.
Reference to unknown value.
Constants
protobuf crate version
This symbol can be referenced to assert that proper version of crate is used
Traits
anything that can be cleared
Trait implemented for all generated structs for protobuf messages.
Trait implemented by all protobuf enum types.
Functions
Parse message from byte array.
Parse message from Bytes
object.
Resulting message may share references to the passed bytes object.
Parse message from reader. Parse stops on EOF or when error encountered.
Parse length-delimited message from stream.
Parse length-delimited message from bytes.
Parse length-delimited message from Read
.