Add docs on extern
keyword
This commit is contained in:
parent
f15a1ec45d
commit
f91ad440ef
1 changed files with 42 additions and 0 deletions
|
@ -179,6 +179,48 @@ mod crate_keyword { }
|
|||
/// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html
|
||||
mod enum_keyword { }
|
||||
|
||||
#[doc(keyword = "extern")]
|
||||
//
|
||||
/// For external connections in Rust code.
|
||||
///
|
||||
/// The `extern` keyword is used in two places in Rust. One is in conjunction with the [`crate`]
|
||||
/// keyword to make your Rust code aware of other Rust crates in your project, i.e. `extern crate
|
||||
/// lazy_static;`. The other use is in foreign function interfaces (FFI).
|
||||
///
|
||||
/// `extern` is used in two different contexts within FFI. The first is in the form of external
|
||||
/// blcoks, for declaring function interfaces that Rust code can call foreign code by.
|
||||
///
|
||||
/// ```rust ignore
|
||||
/// #[link(name = "my_c_library")]
|
||||
/// extern "C" {
|
||||
/// fn my_c_function(x: i32) -> bool;
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// This code would attempt to link with libmy_c_library.so on unix-like systems and
|
||||
/// my_c_library.dll on Windows at runtime, and panic if it can't find something to link to. Rust
|
||||
/// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with
|
||||
/// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs.
|
||||
///
|
||||
/// The mirror use case of FFI is also done via the `extern` keyword:
|
||||
///
|
||||
/// ```rust
|
||||
/// # #![allow(private_no_mangle_fns)]
|
||||
/// #[no_mangle]
|
||||
/// pub extern fn callable_from_c(x: i32) -> bool {
|
||||
/// x % 3 == 0
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// If compiled as a dylib, the resulting .so could then be linked to from a C library, and the
|
||||
/// function could be used as if it was from any other library.
|
||||
///
|
||||
/// For more information on FFI, check the [Rust book] or the [Reference].
|
||||
///
|
||||
/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code
|
||||
/// [Reference]: https://doc.rust-lang.org/reference/items/external-blocks.html
|
||||
mod extern_keyword { }
|
||||
|
||||
#[doc(keyword = "fn")]
|
||||
//
|
||||
/// The `fn` keyword.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue