Macro haphazard::unique_domain
source · macro_rules! unique_domain {
() => { ... };
}
Expand description
Generate a Domain
with an entirely unique domain family.
The generated family implements Singleton
, which enables the use of
AtomicPtr::safe_load
.
Single-call restriction
The code generated by the unique_domain!
macro can only be called once, since it would
violate the requirements of the Singleton
trait. This means that the unique_domain!
macro can’t be called from inside a data structure’s constructor, or in a few other situations.
use haphazard::{Domain, Singleton, unique_domain};
struct DataStructure<F> {
domain: Domain<F>,
}
impl DataStructure<()> {
fn new() -> DataStructure<impl Singleton> {
DataStructure { domain: unique_domain!() }
}
}
fn main() {
let ds_1 = DataStructure::new();
let ds_2 = DataStructure::new(); // Panics since the code generated by the `unique_domain!`
// macro was executed more than once.
}
The unique_domain!
macro will panic when the generated code is called a second time. This
includes any situation where a function containing a unique_domain!
is called more than once,
or a loop containing a unique_domain!
executes more than one iteration.
Since a constructor containing unique_domain!
cannot be called more than once, data structure
authors should not use this macro. Rather, data structure authors should consider one the
following options:
static_unique_domain!
, which creates a single shared domain for all instances of a data structure.- Passing a
Domain<impl Singleton>
in as a parameter to the constructor, (and likely providing a default to useGlobal
). Authors who choose this options should also consider re-exportingunique_domain!
for their consumers. - Using a non-singleton domain. This option requires unsafe code, but is currently the only ‘safe’ way to automatically create a seperate domain for each instance of a data structure.
Notes
The behaviour of unique_domain!
in the case that it is called more than once may not be
stable.