Rust2Go uses FFI to pass data by reference to minimize memory operations. This introduces specific safety responsibilities:

Golang Side

Data received from Rust is referenced. The Golang handler can implement logic arbitrarily, but if you need to use that data outside the function's lifecycle, you must manually perform a deep copy.

Rust Side

You must ensure that the slot pointer of the callback FFI operation and user parameters remain valid when the Future is dropped. To assist with this, Rust2Go provides:

• An atomic slot structure to manage callback state.
• The [drop_safe] attribute, which requires user-passed parameters to have ownership to ensure they aren't dropped prematurely.

You can choose between static and dynamic linking when connecting Go to your Rust library.

Static Linking

• Rust side: Use crate-type = ["staticlib"].
• Go side: Use #cgo LDFLAGS: ./path/to/librust_lib.a.
• Benefit: The resulting Go binary is self-contained regarding the Rust logic.

Dynamic Linking

• Rust side: Use crate-type = ["cdylib"].
• Go side: Use #cgo LDFLAGS: -L. -lrust_lib.
• Runtime: You must distribute the shared library (.so, .dylib, or .dll) alongside your executable. You may need to set LD_LIBRARY_PATH so the OS can find it:

  export LD_LIBRARY_PATH=$(pwd):$LD_LIBRARY_PATH

Bidirectional calling allows Rust to call Go functions and Go to call Rust functions using CGO as the backend. This is achieved by defining a trait in Rust, generating Go interface implementations, and using a build script to link the two.

// In Rust, define your data and trait
#[derive(rust2go::R2G)]
pub struct DemoRequest {
    pub name: String,
    pub age: u8,
}

#[derive(rust2go::R2G)]
pub struct DemoResponse {
    pub pass: bool,
}

#[rust2go::r2g]
pub trait DemoCall {
    fn demo_oneway(req: &DemoRequest);
    fn demo_check(req: DemoRequest) -> DemoResponse;
}

Use the rust2go-cli to generate the Go interface implementation based on your Rust trait definitions.

Run the following command: rust2go-cli --src <path_to_rust_file> --dst <path_to_go_destination>

After generation, you must create a Go file (e.g., impl.go) that defines a struct implementing the generated {$trait} interface. Assign this struct to the {$trait}Impl type to allow Rust to access it.

rust2go-cli --src src/user.rs --dst go/gen.go

To use Rust2Go with the Tokio runtime and a Shared Memory Lockless Queue backend, follow these setup steps:

1. Configure Dependencies

Add rust2go to your Cargo.toml. You must include it in both dependencies and build-dependencies (with the build feature enabled).

2. Install CLI Tool

Install the required command-line tool for code generation:

cargo install --force rust2go-cli

3. Configure Build Script

Create a build.rs file in your Rust project root to automate the Go source integration:

fn main() {
    rust2go::Builder::new().with_go_src("./go").build();
}

[dependencies]
rust2go = { version = "0.4.0" }

[build-dependencies]
rust2go = { version = "0.4.0", features = ["build"] }

To use Rust2Go with the Tokio runtime and a Shared Memory Lockless Queue backend, follow these setup steps:

1. Update Cargo.toml: Add rust2go to both dependencies and build-dependencies (with the build feature enabled).
2. Install CLI: Install the required command-line tool via cargo.
3. Configure Build Script: Create a build.rs to automate the Go source integration.
4. Initialize Go Project: Create a directory for your Go code and initialize a module.

[dependencies]
rust2go = { version = "0.4.0" }

[build-dependencies]
rust2go = { version = "0.4.0", features = ["build"] }

cargo install --force rust2go-cli

In build.rs

fn main() { rust2go::Builder::new().with_go_src("./go").build(); }

After defining your Rust interface, use the rust2go-cli to generate the Go bindings.

1. Generate bindings: Run the CLI pointing to your Rust source file:

   rust2go-cli --src rust-lib/src/user.rs --dst gen.go --without-main

2. Call from Go: Import the generated code and use the {$trait}Impl struct to invoke the methods. You must also include the appropriate cgo LDFLAGS to link the Rust library.

/*
// For statically link:
#cgo LDFLAGS: ./librust_lib.a

// For dynamically link:
#cgo LDFLAGS: -L. -lrust_lib
*/
import "C"

func main() {
    user := DemoUser{
        name: "chihai",
        age:  28,
    }
    // Use the Impl struct to call methods
    G2RCallImpl{}.demo_log(&user.name, &user.age)
    new_name := G2RCallImpl{}.demo_convert_name(&user)
    fmt.Printf("new name: %s", new_name)
}