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:

  1. static_unique_domain!, which creates a single shared domain for all instances of a data structure.
  2. Passing a Domain<impl Singleton> in as a parameter to the constructor, (and likely providing a default to use Global). Authors who choose this options should also consider re-exporting unique_domain! for their consumers.
  3. 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.