1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
/**
The `sabi_extern_fn` attribute macro allows defining `extern "C"` function that
abort on unwind instead of causing undefined behavior.
This macro is syntactic sugar to transform this:
```ignore
<visibility> fn function_name( <params> ) -> <return type> {
<code here>
}
```
into this:
```ignore
<visibility> extern "C" fn function_name( <params> ) -> <return type> {
::abi_stable::extern_fn_panic_handling!{
<code here>
}
}
```
What this attribute does is to give the function abort on unwind semantics
(only when the unwinds doesn't stop inside the function).
A user can still use [`std::panic::catch_unwind`] inside the function to
catch panics and handle them appropriately.
### Basic examples
```rust
use abi_stable::{sabi_extern_fn, std_types::RArc, traits::IntoReprC};
#[sabi_extern_fn]
pub(crate) fn hello() -> RArc<u32> {
RArc::new(100)
}
assert_eq!(hello(), RArc::new(100));
```
```rust
use abi_stable::{
sabi_extern_fn,
std_types::{RStr, RVec},
traits::IntoReprC,
};
#[sabi_extern_fn]
fn collect_into_lines(text: &str) -> RVec<RStr<'_>> {
text.lines()
.filter(|x| !x.is_empty())
.map(RStr::from)
.collect()
}
assert_eq!(
collect_into_lines("what\nis\nthat"),
vec!["what".into_c(), "is".into(), "that".into()].into_c(),
);
```
# no_early_return
You can use `#[sabi_extern_fn(no_early_return)]` to potentially
improve the runtime performance of the annotated function (this has not been tested).
This variant of the attribute removes an intermediate closure that is
used to intercept early returns (`?`, `return`, etc),
If this version of the attribute is used on a function which does have an
early return, it will (incorrectly) abort the process when it attempts to return early.
### Example
```rust
use abi_stable::{
sabi_extern_fn,
std_types::{RStr, RVec},
traits::IntoReprC,
};
#[sabi_extern_fn(no_early_return)]
pub(crate) fn hello() -> RVec<RStr<'static>> {
vec!["hello".into(), "world".into()].into()
}
assert_eq!(hello(), vec!["hello".into_c(), "world".into()].into_c(),);
```
*/
pub use sabi_extern_fn;