1 unstable release
0.1.0 | Jun 28, 2024 |
---|
#338 in FFI
466 downloads per month
Used in 2 crates
13KB
354 lines
Rust2Go
Rust2Go is a project that provides users with a simple and efficient way to call Golang from Rust with native async support.
Features
- Sync and async calls from Rust to Golang
- Efficient data exchange: no serialization or socket communication, but FFI
- Simple interface design: no new invented IDL except for native rust
How to Use
- Define the structs and calling interfaces in restricted Rust syntax, and include generated code in the same file.
- Generate golang code with
rust2go-cli --src src/user.rs --dst go/gen.go
- Write a
build.rs
for you project. - You can then use generated implementation to call golang in your Rust project!
For detailed example, please checkout the example projects.
Key Design
Detailed design details can be found in this article: Design and Implementation of a Rust-Go FFI Framework.
Why Fast?
In order to achieve the ultimate performance, this project is not based on communication, but on FFI to pass specially encoded data. In order to reduce memory operations to a minimum, data that satisfies a specific memory layout is passed directly by reference rather than copied.
For example, Vec<u8>
and String
is represented as a pointer and a length. However, structs like Vec<String>
or Vec<Vec<u8>>
require intermediate representation. In order to reduce the number of memory allocations to one, I use a precomputed size buffer to store these intermediate structures.
Memory Safety
On the Golang side, the data it receives is referenced from Rust. The Rust side will do its best to ensure the validity of this data during the call. So the Golang side can implement the handler arbitrarily, but manually deep copy when leaking data outside the function life cycle.
On the Rust side, it is needed to ensure that the slot pointer of the callback ffi operation, and the user parameters are valid when the future drops. This is archieved by implementing an atomic slot structure and providing a [drop_safe]
attribute to require user passing parameters with ownership.
Toolchain Requirements
- Golang: >=1.18
- For >=1.18 && < 1.20: generate golang code with
--go118
- For >=1.20: generate golang code normally
- For >=1.18 && < 1.20: generate golang code with
- Rust: >=1.75 if you want to use async
Milestones
Init Version
- IDL(in rust) parse
- Go code generation
- Build script helper
- Basic data types and convertion generation
- Rust impl generation
- Future and basic synchronization primitives used
Basic Ability Enhancement
- More complicated data types support
- Support user passing references
- More elegant code generation implementation
- Better build cache control
- Golang interface support(separate user code from generated code)
- Dynamic linking support
- Golang helper library
Performance Optimization
- Shared memory based implementation
Extended Features
- Support calling rust from golang
Credit
This project is inspired by fcplug.