chaud_hot/func/mod.rs
1//! Various representations of a function (pointer).
2//!
3//! # Definitions
4//!
5//! * An **"erased"** function pointer is a function pointer that has been
6//! transmuted into a normal (non-function) pointer.
7//! * The **"actual"** type refers to the non-erased type.
8//!
9//! # Summary
10//!
11//! The types in this module are somewhat layered:
12//!
13//! * [`ErasedFnPtrPointee`] specifies the pointee type used for erased function
14//! pointers. It is defined to be [`c_void`][core::ffi::c_void].
15//! * [`RawErasedFnPtr`] is a raw pointer pointing to [`ErasedFnPtrPointee`]. It
16//! is only used when necessary for interacting with APIs exposed by other
17//! libraries.
18//! * [`ErasedFnPtr`] conceptually wraps a [`RawErasedFnPtr`], but cannot be
19//! `null` (normal function pointers also cannot be `null`). It also
20//! implements [`Send`] and [`Sync`] (which aren't implemented for raw
21//! pointers).
22//! * [`AtomicFnPtr`] conceptually wraps an [`ErasedFnPtr`], allowing it to be
23//! atomically updated.
24//! * [`FuncStorage`] is parmeterized by [`Func`] and stores the corresponding
25//! [`AtomicFnPtr`]. It is the boundary between erased and non-erased (typed)
26//! layers.
27//!
28//! # Safety
29//!
30//! With the exception of [`ErasedFnPtrPointee`] and [`RawErasedFnPtr`] (which
31//! are type aliases), all types defined in this module impose similar safety
32//! requirements:
33//!
34//! 1) The **actual** type of the stored value must **never** change, and always
35//! be a function pointer implementing [`FnPtrLike`].
36//! * This implies that stored values are always non-null.
37//!
38//! 2) With the exception of [`AtomicFnPtr`], the stored **value** must never
39//! change.
40//! * This makes it easier to reason about (1).
41//!
42//! # Code Style
43//!
44//! * Every field should be considered an "unsafe" field and will be marked as
45//! such once
46//! [RFC 3458](https://github.com/rust-lang/rust/issues/132922) is
47//! stable.
48//! * Methods should be `pub(super)` until they are needed outside this module.
49
50pub use self::atomic::*;
51pub use self::def::*;
52pub use self::ptr::*;
53pub use self::storage::*;
54
55mod atomic;
56mod def;
57mod ptr;
58mod storage;