Rust Language Bindings for Thrift
Installation
This method support over Rust 1.7. :
cargo install rthrift_tutorial
From source
-
Clone the repository
git clone https://github.com/okanon/rthrift_tutorial.git
-
cd rthrift; cargo build --release
. The binary will now be in./target/release/rthrift_tutorial_server
-
Add the binary to your
PATH
. This can be done by moving it to a directory already in yourPATH
(i.e./usr/local/bin
) or by adding the./target/release/
directory to yourPATH
Getting Started
-
Get the Thrift compiler.
-
Add the following crates to your
Cargo.toml
.
= "x.y.z" # x.y.z is the version of the thrift compiler
= "0.3.0"
= "0.2.0"
- Add the same crates to your
lib.rs
ormain.rs
.
extern crate ordered_float;
extern crate thrift;
extern crate try_from;
- Generate Rust sources for your IDL (for example,
Tutorial.thrift
).
thrift -out my_rust_program/src --gen rs -r Tutorial.thrift
- Use the generated source in your code.
// add extern crates here, or in your lib.rs
extern crate ordered_float;
extern crate thrift;
extern crate try_from;
// generated Rust module
use tutorial;
use ;
use ;
use ;
use ;
use ;
use ;
Code Generation
Thrift Files and Generated Modules
The Thrift code generator takes each Thrift file and generates a Rust module
with the same name snake-cased. For example, running the compiler on
ThriftTest.thrift
creates thrift_test.rs
. To use these generated files add
mod ...
and use ...
declarations to your lib.rs
or main.rs
- one for
each generated file.
Results and Errors
The Thrift runtime library defines a thrift::Result
and a thrift::Error
type,
both of which are used throught the runtime library and in all generated code.
Conversions are defined from std::io::Error
, str
and String
into
thrift::Error
.
Thrift Type and their Rust Equivalents
Thrift defines a number of types, each of which is translated into its Rust equivalent by the code generator.
- Primitives (bool, i8, i16, i32, i64, double, string, binary)
- Typedefs
- Enums
- Containers
- Structs
- Unions
- Exceptions
- Services
- Constants (primitives, containers, structs)
In addition, unless otherwise noted, thrift includes are translated into
use ...
statements in the generated code, and all declarations, parameters,
traits and types in the generated code are namespaced appropriately.
The following subsections cover each type and their generated Rust equivalent.
Primitives
Thrift primitives have straightforward Rust equivalents.
- bool:
bool
- i8:
i8
- i16:
i16
- i32:
i32
- i64:
i64
- double:
OrderedFloat<f64>
- string:
String
- binary:
Vec<u8>
Typedefs
A typedef is translated to a pub type
declaration.
typedef i64 UserId
typedef map<string, UserId> MapType
pub type UserId = i64;
pub type MapType = ;
Enums
A Thrift enum is represented as a Rust enum, and each variant is transcribed 1:1.
enum Numberz
{
ONE = 1,
TWO,
THREE,
FIVE = 5,
SIX,
EIGHT = 8
}
Containers
Thrift has three container types: list, set and map. They are translated into
Rust Vec
, BTreeSet
and BTreeMap
respectively. Any Thrift type (this
includes structs, enums and typedefs) can be a list/set element or a map
key/value.
List
list <i32> numbers
numbers:
Set
set <i32> numbers
numbers:
Map
map <string, i32> numbers
numbers:
Structs
A Thrift struct is represented as a Rust struct, and each field transcribed 1:1.
struct CrazyNesting {
1: string string_field,
2: optional set<Insanity> set_field,
3: required list<
map<set<i32>, map<i32,set<list<map<Insanity,string>>>>>
>
4: binary binary_field
}
Optionality
Thrift has 3 "optionality" types:
- Required
- Optional
- Default
The Rust code generator encodes Required fields as the bare type itself, while
Optional and Default fields are encoded as Option<TypeName>
.
struct Foo {
1: required string bar // 1. required
2: optional string baz // 2. optional
3: string qux // 3. default
}
Known Issues
- Struct constants are not supported
- Map, list and set constants require a const holder struct