|
1.
|
|
|
% The Rust Foreign Function Interface Guide
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:2
|
|
2.
|
|
|
# Introduction
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:4 src/doc/guide-lifetimes.md:4
src/doc/guide-macros.md:13 src/doc/guide-plugin.md:28
src/doc/guide-tasks.md:4 src/doc/guide-unsafe.md:4
|
|
3.
|
|
|
This guide will use the [snappy](https://github.com/google/snappy) compression/decompression library as an introduction to writing bindings for foreign code. Rust is currently unable to call directly into a C++ library, but snappy includes a C interface (documented in [`snappy-c.h`](https://github.com/google/snappy/blob/master/snappy-c.h)).
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:10
|
|
4.
|
|
|
The following is a minimal example of calling a foreign function which will compile if snappy is installed:
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:13
|
|
5.
|
|
|
~~~~no_run extern crate libc; use libc::size_t;
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:17
|
|
6.
|
|
|
#[link(name = "snappy")]
extern {
fn snappy_max_compressed_length(source_length: size_t) -> size_t;
}
|
|
|
type: Plain text
|
|
|
represents a line break.
Start a new line in the equivalent position in the translation.
|
|
|
represents a space character.
Enter a space in the equivalent position in the translation.
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:22
|
|
7.
|
|
|
fn main() {
let x = unsafe { snappy_max_compressed_length(100) };
println!("max compressed length of a 100 byte buffer: {}", x);
}
~~~~
|
|
|
type: Plain text
|
|
|
represents a line break.
Start a new line in the equivalent position in the translation.
|
|
|
represents a space character.
Enter a space in the equivalent position in the translation.
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:28
|
|
8.
|
|
|
The `extern` block is a list of function signatures in a foreign library, in this case with the platform's C ABI. The `#[link(...)]` attribute is used to instruct the linker to link against the snappy library so the symbols are resolved.
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:33
|
|
9.
|
|
|
Foreign functions are assumed to be unsafe so calls to them need to be wrapped with `unsafe {}` as a promise to the compiler that everything contained within truly is safe. C libraries often expose interfaces that aren't thread-safe, and almost any function that takes a pointer argument isn't valid for all possible inputs since the pointer could be dangling, and raw pointers fall outside of Rust's safe memory model.
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:40
|
|
10.
|
|
|
When declaring the argument types to a foreign function, the Rust compiler can not check if the declaration is correct, so specifying it correctly is part of keeping the binding correct at runtime.
|
|
|
type: Plain text
|
|
|
|
(no translation yet)
|
|
|
|
Located in
src/doc/guide-ffi.md:44
|