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
//! # Wrapping Terrible C++
//!
//! Suppose we're using the following terrible C++ library:
//! ```cpp
//! ```
//!
//! There's a lot wrong with this library. We'll ignore:
//! * Vague string encoding (ASCII? UTF8? Windows-1251? System Locale? Which one?)
//! * Potential for [static initialization order fiasco](https://en.cppreference.com/w/cpp/language/siof).
//! * [`std::bad_alloc` exceptions](https://en.cppreference.com/w/cpp/memory/new/bad_alloc) could cross FFI boundaries.
//! * Probably more I haven't bothered to list.
//!
//! However, if we can at least assume we're the only user of this library,
//! <code>[Valrow]\[[Mut](ValrowMut)\]</code> and ZSTs can help us tackle *these* issues:
//! * Not reentrant (e.g. calling `add_user` from within `per_user` results in undefined behavior via invalidated iterators.)<br>
//! Fixed by guarding global state with singleton ZSTs.<br>
//! <br>
//! * No thread safety (e.g. calling `add_user` from multiple threads is undefined behavior.)<br>
//! Fixed by putting said singleton ZSTs within rust-owned [`Mutex`](std::sync::Mutex)es.<br>
//! <br>
//! * No context parameters for callbacks (no sane way to pass captured lambda state.)<br>
//! Fixed by static asserting `FnMut()`s are ZSTs, which can still capture borrows via <code>[Valrow]\[[Mut](ValrowMut)\]</code>.
//! <br>
//!
//! # Demonstration
//! ```
//! #
//! # mod cxx { // mimic ircd.cpp in raw Rust
//! # #![allow(non_upper_case_globals)]
//! # use abistr::*;
//! # use std::ffi::CString;
//! #
//! # static mut channels : Vec<CString> = Vec::new();
//! # static mut users : Vec<CString> = Vec::new();
//! #
//! # #[no_mangle] extern "C" fn add_channel (channel: CStrPtr ) { unsafe { channels.push(channel.to_cstr().into()) } }
//! # #[no_mangle] extern "C" fn add_user (user: CStrPtr ) { unsafe { users .push(user .to_cstr().into()) } }
//! # #[no_mangle] extern "C" fn for_each_channel (per_channel: extern "C" fn(CStrPtr) ) { unsafe { for channel in channels.iter() { per_channel((&**channel).into()) } } }
//! # #[no_mangle] extern "C" fn for_each_user (per_user: extern "C" fn(CStrPtr) ) { unsafe { for user in users .iter() { per_user( (&**user ).into()) } } }
//! # }
//! ```
use crate::*;