src/doc/book/ffi.md

   1 % Foreign Function Interface
   2
   3 # Introduction
   4
   5 This guide will use the [snappy](https://github.com/google/snappy)
   6 compression/decompression library as an introduction to writing bindings for
   7 foreign code. Rust is currently unable to call directly into a C++ library, but
   8 snappy includes a C interface (documented in
   9 [`snappy-c.h`](https://github.com/google/snappy/blob/master/snappy-c.h)).
  10
  11 ## A note about libc
  12
  13 Many of these examples use [the `libc` crate][libc], which provides various
  14 type definitions for C types, among other things. If you’re trying these
  15 examples yourself, you’ll need to add `libc` to your `Cargo.toml`:
  16
  17 ```toml
  18 [dependencies]
  19 libc = "0.2.0"
  20 ```
  21
  22 [libc]: https://crates.io/crates/libc
  23
  24 and add `extern crate libc;` to your crate root.
  25
  26 ## Calling foreign functions
  27
  28 The following is a minimal example of calling a foreign function which will
  29 compile if snappy is installed:
  30
  31 ```rust,no_run
  32 # #![feature(libc)]
  33 extern crate libc;
  34 use libc::size_t;
  35
  36 #[link(name = "snappy")]
  37 extern {
  38     fn snappy_max_compressed_length(source_length: size_t) -> size_t;
  39 }
  40
  41 fn main() {
  42     let x = unsafe { snappy_max_compressed_length(100) };
  43     println!("max compressed length of a 100 byte buffer: {}", x);
  44 }
  45 ```
  46
  47 The `extern` block is a list of function signatures in a foreign library, in
  48 this case with the platform's C ABI. The `#[link(...)]` attribute is used to
  49 instruct the linker to link against the snappy library so the symbols are
  50 resolved.
  51
  52 Foreign functions are assumed to be unsafe so calls to them need to be wrapped
  53 with `unsafe {}` as a promise to the compiler that everything contained within
  54 truly is safe. C libraries often expose interfaces that aren't thread-safe, and
  55 almost any function that takes a pointer argument isn't valid for all possible
  56 inputs since the pointer could be dangling, and raw pointers fall outside of
  57 Rust's safe memory model.
  58
  59 When declaring the argument types to a foreign function, the Rust compiler can
  60 not check if the declaration is correct, so specifying it correctly is part of
  61 keeping the binding correct at runtime.
  62
  63 The `extern` block can be extended to cover the entire snappy API:
  64
  65 ```rust,no_run
  66 # #![feature(libc)]
  67 extern crate libc;
  68 use libc::{c_int, size_t};
  69
  70 #[link(name = "snappy")]
  71 extern {
  72     fn snappy_compress(input: *const u8,
  73                        input_length: size_t,
  74                        compressed: *mut u8,
  75                        compressed_length: *mut size_t) -> c_int;
  76     fn snappy_uncompress(compressed: *const u8,
  77                          compressed_length: size_t,
  78                          uncompressed: *mut u8,
  79                          uncompressed_length: *mut size_t) -> c_int;
  80     fn snappy_max_compressed_length(source_length: size_t) -> size_t;
  81     fn snappy_uncompressed_length(compressed: *const u8,
  82                                   compressed_length: size_t,
  83                                   result: *mut size_t) -> c_int;
  84     fn snappy_validate_compressed_buffer(compressed: *const u8,
  85                                          compressed_length: size_t) -> c_int;
  86 }
  87 # fn main() {}
  88 ```
  89
  90 # Creating a safe interface
  91
  92 The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts
  93 like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe
  94 internal details.
  95
  96 Wrapping the functions which expect buffers involves using the `slice::raw` module to manipulate Rust
  97 vectors as pointers to memory. Rust's vectors are guaranteed to be a contiguous block of memory. The
  98 length is number of elements currently contained, and the capacity is the total size in elements of
  99 the allocated memory. The length is less than or equal to the capacity.
 100
 101 ```rust
 102 # #![feature(libc)]
 103 # extern crate libc;
 104 # use libc::{c_int, size_t};
 105 # unsafe fn snappy_validate_compressed_buffer(_: *const u8, _: size_t) -> c_int { 0 }
 106 # fn main() {}
 107 pub fn validate_compressed_buffer(src: &[u8]) -> bool {
 108     unsafe {
 109         snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0
 110     }
 111 }
 112 ```
 113
 114 The `validate_compressed_buffer` wrapper above makes use of an `unsafe` block, but it makes the
 115 guarantee that calling it is safe for all inputs by leaving off `unsafe` from the function
 116 signature.
 117
 118 The `snappy_compress` and `snappy_uncompress` functions are more complex, since a buffer has to be
 119 allocated to hold the output too.
 120
 121 The `snappy_max_compressed_length` function can be used to allocate a vector with the maximum
 122 required capacity to hold the compressed output. The vector can then be passed to the
 123 `snappy_compress` function as an output parameter. An output parameter is also passed to retrieve
 124 the true length after compression for setting the length.
 125
 126 ```rust
 127 # #![feature(libc)]
 128 # extern crate libc;
 129 # use libc::{size_t, c_int};
 130 # unsafe fn snappy_compress(a: *const u8, b: size_t, c: *mut u8,
 131 #                           d: *mut size_t) -> c_int { 0 }
 132 # unsafe fn snappy_max_compressed_length(a: size_t) -> size_t { a }
 133 # fn main() {}
 134 pub fn compress(src: &[u8]) -> Vec<u8> {
 135     unsafe {
 136         let srclen = src.len() as size_t;
 137         let psrc = src.as_ptr();
 138
 139         let mut dstlen = snappy_max_compressed_length(srclen);
 140         let mut dst = Vec::with_capacity(dstlen as usize);
 141         let pdst = dst.as_mut_ptr();
 142
 143         snappy_compress(psrc, srclen, pdst, &mut dstlen);
 144         dst.set_len(dstlen as usize);
 145         dst
 146     }
 147 }
 148 ```
 149
 150 Decompression is similar, because snappy stores the uncompressed size as part of the compression
 151 format and `snappy_uncompressed_length` will retrieve the exact buffer size required.
 152
 153 ```rust
 154 # #![feature(libc)]
 155 # extern crate libc;
 156 # use libc::{size_t, c_int};
 157 # unsafe fn snappy_uncompress(compressed: *const u8,
 158 #                             compressed_length: size_t,
 159 #                             uncompressed: *mut u8,
 160 #                             uncompressed_length: *mut size_t) -> c_int { 0 }
 161 # unsafe fn snappy_uncompressed_length(compressed: *const u8,
 162 #                                      compressed_length: size_t,
 163 #                                      result: *mut size_t) -> c_int { 0 }
 164 # fn main() {}
 165 pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> {
 166     unsafe {
 167         let srclen = src.len() as size_t;
 168         let psrc = src.as_ptr();
 169
 170         let mut dstlen: size_t = 0;
 171         snappy_uncompressed_length(psrc, srclen, &mut dstlen);
 172
 173         let mut dst = Vec::with_capacity(dstlen as usize);
 174         let pdst = dst.as_mut_ptr();
 175
 176         if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {
 177             dst.set_len(dstlen as usize);
 178             Some(dst)
 179         } else {
 180             None // SNAPPY_INVALID_INPUT
 181         }
 182     }
 183 }
 184 ```
 185
 186 Then, we can add some tests to show how to use them.
 187
 188 ```rust
 189 # #![feature(libc)]
 190 # extern crate libc;
 191 # use libc::{c_int, size_t};
 192 # unsafe fn snappy_compress(input: *const u8,
 193 #                           input_length: size_t,
 194 #                           compressed: *mut u8,
 195 #                           compressed_length: *mut size_t)
 196 #                           -> c_int { 0 }
 197 # unsafe fn snappy_uncompress(compressed: *const u8,
 198 #                             compressed_length: size_t,
 199 #                             uncompressed: *mut u8,
 200 #                             uncompressed_length: *mut size_t)
 201 #                             -> c_int { 0 }
 202 # unsafe fn snappy_max_compressed_length(source_length: size_t) -> size_t { 0 }
 203 # unsafe fn snappy_uncompressed_length(compressed: *const u8,
 204 #                                      compressed_length: size_t,
 205 #                                      result: *mut size_t)
 206 #                                      -> c_int { 0 }
 207 # unsafe fn snappy_validate_compressed_buffer(compressed: *const u8,
 208 #                                             compressed_length: size_t)
 209 #                                             -> c_int { 0 }
 210 # fn main() { }
 211
 212 #[cfg(test)]
 213 mod tests {
 214     use super::*;
 215
 216     #[test]
 217     fn valid() {
 218         let d = vec![0xde, 0xad, 0xd0, 0x0d];
 219         let c: &[u8] = &compress(&d);
 220         assert!(validate_compressed_buffer(c));
 221         assert!(uncompress(c) == Some(d));
 222     }
 223
 224     #[test]
 225     fn invalid() {
 226         let d = vec![0, 0, 0, 0];
 227         assert!(!validate_compressed_buffer(&d));
 228         assert!(uncompress(&d).is_none());
 229     }
 230
 231     #[test]
 232     fn empty() {
 233         let d = vec![];
 234         assert!(!validate_compressed_buffer(&d));
 235         assert!(uncompress(&d).is_none());
 236         let c = compress(&d);
 237         assert!(validate_compressed_buffer(&c));
 238         assert!(uncompress(&c) == Some(d));
 239     }
 240 }
 241 ```
 242
 243 # Destructors
 244
 245 Foreign libraries often hand off ownership of resources to the calling code.
 246 When this occurs, we must use Rust's destructors to provide safety and guarantee
 247 the release of these resources (especially in the case of panic).
 248
 249 For more about destructors, see the [Drop trait](../std/ops/trait.Drop.html).
 250
 251 # Callbacks from C code to Rust functions
 252
 253 Some external libraries require the usage of callbacks to report back their
 254 current state or intermediate data to the caller.
 255 It is possible to pass functions defined in Rust to an external library.
 256 The requirement for this is that the callback function is marked as `extern`
 257 with the correct calling convention to make it callable from C code.
 258
 259 The callback function can then be sent through a registration call
 260 to the C library and afterwards be invoked from there.
 261
 262 A basic example is:
 263
 264 Rust code:
 265
 266 ```rust,no_run
 267 extern fn callback(a: i32) {
 268     println!("I'm called from C with value {0}", a);
 269 }
 270
 271 #[link(name = "extlib")]
 272 extern {
 273    fn register_callback(cb: extern fn(i32)) -> i32;
 274    fn trigger_callback();
 275 }
 276
 277 fn main() {
 278     unsafe {
 279         register_callback(callback);
 280         trigger_callback(); // Triggers the callback
 281     }
 282 }
 283 ```
 284
 285 C code:
 286
 287 ```c
 288 typedef void (*rust_callback)(int32_t);
 289 rust_callback cb;
 290
 291 int32_t register_callback(rust_callback callback) {
 292     cb = callback;
 293     return 1;
 294 }
 295
 296 void trigger_callback() {
 297   cb(7); // Will call callback(7) in Rust
 298 }
 299 ```
 300
 301 In this example Rust's `main()` will call `trigger_callback()` in C,
 302 which would, in turn, call back to `callback()` in Rust.
 303
 304
 305 ## Targeting callbacks to Rust objects
 306
 307 The former example showed how a global function can be called from C code.
 308 However it is often desired that the callback is targeted to a special
 309 Rust object. This could be the object that represents the wrapper for the
 310 respective C object.
 311
 312 This can be achieved by passing an raw pointer to the object down to the
 313 C library. The C library can then include the pointer to the Rust object in
 314 the notification. This will allow the callback to unsafely access the
 315 referenced Rust object.
 316
 317 Rust code:
 318
 319 ```rust,no_run
 320 #[repr(C)]
 321 struct RustObject {
 322     a: i32,
 323     // other members
 324 }
 325
 326 extern "C" fn callback(target: *mut RustObject, a: i32) {
 327     println!("I'm called from C with value {0}", a);
 328     unsafe {
 329         // Update the value in RustObject with the value received from the callback
 330         (*target).a = a;
 331     }
 332 }
 333
 334 #[link(name = "extlib")]
 335 extern {
 336    fn register_callback(target: *mut RustObject,
 337                         cb: extern fn(*mut RustObject, i32)) -> i32;
 338    fn trigger_callback();
 339 }
 340
 341 fn main() {
 342     // Create the object that will be referenced in the callback
 343     let mut rust_object = Box::new(RustObject { a: 5 });
 344
 345     unsafe {
 346         register_callback(&mut *rust_object, callback);
 347         trigger_callback();
 348     }
 349 }
 350 ```
 351
 352 C code:
 353
 354 ```c
 355 typedef void (*rust_callback)(void*, int32_t);
 356 void* cb_target;
 357 rust_callback cb;
 358
 359 int32_t register_callback(void* callback_target, rust_callback callback) {
 360     cb_target = callback_target;
 361     cb = callback;
 362     return 1;
 363 }
 364
 365 void trigger_callback() {
 366   cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust
 367 }
 368 ```
 369
 370 ## Asynchronous callbacks
 371
 372 In the previously given examples the callbacks are invoked as a direct reaction
 373 to a function call to the external C library.
 374 The control over the current thread is switched from Rust to C to Rust for the
 375 execution of the callback, but in the end the callback is executed on the
 376 same thread that called the function which triggered the callback.
 377
 378 Things get more complicated when the external library spawns its own threads
 379 and invokes callbacks from there.
 380 In these cases access to Rust data structures inside the callbacks is
 381 especially unsafe and proper synchronization mechanisms must be used.
 382 Besides classical synchronization mechanisms like mutexes, one possibility in
 383 Rust is to use channels (in `std::sync::mpsc`) to forward data from the C
 384 thread that invoked the callback into a Rust thread.
 385
 386 If an asynchronous callback targets a special object in the Rust address space
 387 it is also absolutely necessary that no more callbacks are performed by the
 388 C library after the respective Rust object gets destroyed.
 389 This can be achieved by unregistering the callback in the object's
 390 destructor and designing the library in a way that guarantees that no
 391 callback will be performed after deregistration.
 392
 393 # Linking
 394
 395 The `link` attribute on `extern` blocks provides the basic building block for
 396 instructing rustc how it will link to native libraries. There are two accepted
 397 forms of the link attribute today:
 398
 399 * `#[link(name = "foo")]`
 400 * `#[link(name = "foo", kind = "bar")]`
 401
 402 In both of these cases, `foo` is the name of the native library that we're
 403 linking to, and in the second case `bar` is the type of native library that the
 404 compiler is linking to. There are currently three known types of native
 405 libraries:
 406
 407 * Dynamic - `#[link(name = "readline")]`
 408 * Static - `#[link(name = "my_build_dependency", kind = "static")]`
 409 * Frameworks - `#[link(name = "CoreFoundation", kind = "framework")]`
 410
 411 Note that frameworks are only available on OSX targets.
 412
 413 The different `kind` values are meant to differentiate how the native library
 414 participates in linkage. From a linkage perspective, the Rust compiler creates
 415 two flavors of artifacts: partial (rlib/staticlib) and final (dylib/binary).
 416 Native dynamic library and framework dependencies are propagated to the final
 417 artifact boundary, while static library dependencies are not propagated at
 418 all, because the static libraries are integrated directly into the subsequent
 419 artifact.
 420
 421 A few examples of how this model can be used are:
 422
 423 * A native build dependency. Sometimes some C/C++ glue is needed when writing
 424   some Rust code, but distribution of the C/C++ code in a library format is
 425   a burden. In this case, the code will be archived into `libfoo.a` and then the
 426   Rust crate would declare a dependency via `#[link(name = "foo", kind =
 427   "static")]`.
 428
 429   Regardless of the flavor of output for the crate, the native static library
 430   will be included in the output, meaning that distribution of the native static
 431   library is not necessary.
 432
 433 * A normal dynamic dependency. Common system libraries (like `readline`) are
 434   available on a large number of systems, and often a static copy of these
 435   libraries cannot be found. When this dependency is included in a Rust crate,
 436   partial targets (like rlibs) will not link to the library, but when the rlib
 437   is included in a final target (like a binary), the native library will be
 438   linked in.
 439
 440 On OSX, frameworks behave with the same semantics as a dynamic library.
 441
 442 # Unsafe blocks
 443
 444 Some operations, like dereferencing raw pointers or calling functions that have been marked
 445 unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to
 446 the compiler that the unsafety does not leak out of the block.
 447
 448 Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like
 449 this:
 450
 451 ```rust
 452 unsafe fn kaboom(ptr: *const i32) -> i32 { *ptr }
 453 ```
 454
 455 This function can only be called from an `unsafe` block or another `unsafe` function.
 456
 457 # Accessing foreign globals
 458
 459 Foreign APIs often export a global variable which could do something like track
 460 global state. In order to access these variables, you declare them in `extern`
 461 blocks with the `static` keyword:
 462
 463 ```rust,no_run
 464 # #![feature(libc)]
 465 extern crate libc;
 466
 467 #[link(name = "readline")]
 468 extern {
 469     static rl_readline_version: libc::c_int;
 470 }
 471
 472 fn main() {
 473     println!("You have readline version {} installed.",
 474              unsafe { rl_readline_version as i32 });
 475 }
 476 ```
 477
 478 Alternatively, you may need to alter global state provided by a foreign
 479 interface. To do this, statics can be declared with `mut` so we can mutate
 480 them.
 481
 482 ```rust,no_run
 483 # #![feature(libc)]
 484 extern crate libc;
 485
 486 use std::ffi::CString;
 487 use std::ptr;
 488
 489 #[link(name = "readline")]
 490 extern {
 491     static mut rl_prompt: *const libc::c_char;
 492 }
 493
 494 fn main() {
 495     let prompt = CString::new("[my-awesome-shell] $").unwrap();
 496     unsafe {
 497         rl_prompt = prompt.as_ptr();
 498
 499         println!("{:?}", rl_prompt);
 500
 501         rl_prompt = ptr::null();
 502     }
 503 }
 504 ```
 505
 506 Note that all interaction with a `static mut` is unsafe, both reading and
 507 writing. Dealing with global mutable state requires a great deal of care.
 508
 509 # Foreign calling conventions
 510
 511 Most foreign code exposes a C ABI, and Rust uses the platform's C calling convention by default when
 512 calling foreign functions. Some foreign functions, most notably the Windows API, use other calling
 513 conventions. Rust provides a way to tell the compiler which convention to use:
 514
 515 ```rust
 516 # #![feature(libc)]
 517 extern crate libc;
 518
 519 #[cfg(all(target_os = "win32", target_arch = "x86"))]
 520 #[link(name = "kernel32")]
 521 #[allow(non_snake_case)]
 522 extern "stdcall" {
 523     fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int;
 524 }
 525 # fn main() { }
 526 ```
 527
 528 This applies to the entire `extern` block. The list of supported ABI constraints
 529 are:
 530
 531 * `stdcall`
 532 * `aapcs`
 533 * `cdecl`
 534 * `fastcall`
 535 * `vectorcall`
 536 This is currently hidden behind the `abi_vectorcall` gate and is subject to change.
 537 * `Rust`
 538 * `rust-intrinsic`
 539 * `system`
 540 * `C`
 541 * `win64`
 542 * `sysv64`
 543
 544 Most of the abis in this list are self-explanatory, but the `system` abi may
 545 seem a little odd. This constraint selects whatever the appropriate ABI is for
 546 interoperating with the target's libraries. For example, on win32 with a x86
 547 architecture, this means that the abi used would be `stdcall`. On x86_64,
 548 however, windows uses the `C` calling convention, so `C` would be used. This
 549 means that in our previous example, we could have used `extern "system" { ... }`
 550 to define a block for all windows systems, not only x86 ones.
 551
 552 # Interoperability with foreign code
 553
 554 Rust guarantees that the layout of a `struct` is compatible with the platform's
 555 representation in C only if the `#[repr(C)]` attribute is applied to it.
 556 `#[repr(C, packed)]` can be used to lay out struct members without padding.
 557 `#[repr(C)]` can also be applied to an enum.
 558
 559 Rust's owned boxes (`Box<T>`) use non-nullable pointers as handles which point
 560 to the contained object. However, they should not be manually created because
 561 they are managed by internal allocators. References can safely be assumed to be
 562 non-nullable pointers directly to the type.  However, breaking the borrow
 563 checking or mutability rules is not guaranteed to be safe, so prefer using raw
 564 pointers (`*`) if that's needed because the compiler can't make as many
 565 assumptions about them.
 566
 567 Vectors and strings share the same basic memory layout, and utilities are
 568 available in the `vec` and `str` modules for working with C APIs. However,
 569 strings are not terminated with `\0`. If you need a NUL-terminated string for
 570 interoperability with C, you should use the `CString` type in the `std::ffi`
 571 module.
 572
 573 The [`libc` crate on crates.io][libc] includes type aliases and function
 574 definitions for the C standard library in the `libc` module, and Rust links
 575 against `libc` and `libm` by default.
 576
 577 # The "nullable pointer optimization"
 578
 579 Certain Rust types are defined to never be `null`. This includes references (`&T`,
 580 `&mut T`), boxes (`Box<T>`), and function pointers (`extern "abi" fn()`). When
 581 interfacing with C, pointers that might be `null` are often used, which would seem to
 582 require some messy `transmute`s and/or unsafe code to handle conversions to/from Rust types.
 583 However, the language provides a workaround.
 584
 585 As a special case, an `enum` is eligible for the "nullable pointer optimization" if it contains
 586 exactly two variants, one of which contains no data and the other contains a field of one of the
 587 non-nullable types listed above.  This means no extra space is required for a discriminant; rather,
 588 the empty variant is represented by putting a `null` value into the non-nullable field. This is
 589 called an "optimization", but unlike other optimizations it is guaranteed to apply to eligible
 590 types.
 591
 592 The most common type that takes advantage of the nullable pointer optimization is `Option<T>`,
 593 where `None` corresponds to `null`. So `Option<extern "C" fn(c_int) -> c_int>` is a correct way
 594 to represent a nullable function pointer using the C ABI (corresponding to the C type
 595 `int (*)(int)`).
 596
 597 Here is a contrived example. Let's say some C library has a facility for registering a
 598 callback, which gets called in certain situations. The callback is passed a function pointer
 599 and an integer and it is supposed to run the function with the integer as a parameter. So
 600 we have function pointers flying across the FFI boundary in both directions.
 601
 602 ```rust
 603 # #![feature(libc)]
 604 extern crate libc;
 605 use libc::c_int;
 606
 607 # #[cfg(hidden)]
 608 extern "C" {
 609     /// Register the callback.
 610     fn register(cb: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>, c_int) -> c_int>);
 611 }
 612 # unsafe fn register(_: Option<extern "C" fn(Option<extern "C" fn(c_int) -> c_int>,
 613 #                                            c_int) -> c_int>)
 614 # {}
 615
 616 /// This fairly useless function receives a function pointer and an integer
 617 /// from C, and returns the result of calling the function with the integer.
 618 /// In case no function is provided, it squares the integer by default.
 619 extern "C" fn apply(process: Option<extern "C" fn(c_int) -> c_int>, int: c_int) -> c_int {
 620     match process {
 621         Some(f) => f(int),
 622         None    => int * int
 623     }
 624 }
 625
 626 fn main() {
 627     unsafe {
 628         register(Some(apply));
 629     }
 630 }
 631 ```
 632
 633 And the code on the C side looks like this:
 634
 635 ```c
 636 void register(void (*f)(void (*)(int), int)) {
 637     ...
 638 }
 639 ```
 640
 641 No `transmute` required!
 642
 643 # Calling Rust code from C
 644
 645 You may wish to compile Rust code in a way so that it can be called from C. This is
 646 fairly easy, but requires a few things:
 647
 648 ```rust
 649 #[no_mangle]
 650 pub extern fn hello_rust() -> *const u8 {
 651     "Hello, world!\0".as_ptr()
 652 }
 653 # fn main() {}
 654 ```
 655
 656 The `extern` makes this function adhere to the C calling convention, as
 657 discussed above in "[Foreign Calling
 658 Conventions](ffi.html#foreign-calling-conventions)". The `no_mangle`
 659 attribute turns off Rust's name mangling, so that it is easier to link to.
 660
 661 # FFI and panics
 662
 663 It’s important to be mindful of `panic!`s when working with FFI. A `panic!`
 664 across an FFI boundary is undefined behavior. If you’re writing code that may
 665 panic, you should run it in another thread, so that the panic doesn’t bubble up
 666 to C:
 667
 668 ```rust
 669 use std::thread;
 670
 671 #[no_mangle]
 672 pub extern fn oh_no() -> i32 {
 673     let h = thread::spawn(|| {
 674         panic!("Oops!");
 675     });
 676
 677     match h.join() {
 678         Ok(_) => 1,
 679         Err(_) => 0,
 680     }
 681 }
 682 # fn main() {}
 683 ```
 684
 685 # Representing opaque structs
 686
 687 Sometimes, a C library wants to provide a pointer to something, but not let you
 688 know the internal details of the thing it wants. The simplest way is to use a
 689 `void *` argument:
 690
 691 ```c
 692 void foo(void *arg);
 693 void bar(void *arg);
 694 ```
 695
 696 We can represent this in Rust with the `c_void` type:
 697
 698 ```rust
 699 # #![feature(libc)]
 700 extern crate libc;
 701
 702 extern "C" {
 703     pub fn foo(arg: *mut libc::c_void);
 704     pub fn bar(arg: *mut libc::c_void);
 705 }
 706 # fn main() {}
 707 ```
 708
 709 This is a perfectly valid way of handling the situation. However, we can do a bit
 710 better. To solve this, some C libraries will instead create a `struct`, where
 711 the details and memory layout of the struct are private. This gives some amount
 712 of type safety. These structures are called ‘opaque’. Here’s an example, in C:
 713
 714 ```c
 715 struct Foo; /* Foo is a structure, but its contents are not part of the public interface */
 716 struct Bar;
 717 void foo(struct Foo *arg);
 718 void bar(struct Bar *arg);
 719 ```
 720
 721 To do this in Rust, let’s create our own opaque types with `enum`:
 722
 723 ```rust
 724 pub enum Foo {}
 725 pub enum Bar {}
 726
 727 extern "C" {
 728     pub fn foo(arg: *mut Foo);
 729     pub fn bar(arg: *mut Bar);
 730 }
 731 # fn main() {}
 732 ```
 733
 734 By using an `enum` with no variants, we create an opaque type that we can’t
 735 instantiate, as it has no variants. But because our `Foo` and `Bar` types are
 736 different, we’ll get type safety between the two of them, so we cannot
 737 accidentally pass a pointer to `Foo` to `bar()`.