Trait rayon_core::latch::Latch

source · 
pub(crate) trait Latch {
    // Required method
    unsafe fn set(this: *const Self);
}
Expand description

We define various kinds of latches, which are all a primitive signaling mechanism. A latch starts as false. Eventually someone calls set() and it becomes true. You can test if it has been set by calling probe().

Some kinds of latches, but not all, support a wait() operation that will wait until the latch is set, blocking efficiently. That is not part of the trait since it is not possibly to do with all latches.

The intention is that set() is called once, but probe() may be called any number of times. Once probe() returns true, the memory effects that occurred before set() become visible.

It’d probably be better to refactor the API into two paired types, but that’s a bit of work, and this is not a public API.

§Memory ordering

Latches need to guarantee two things:

  • Once probe() returns true, all memory effects from the set() are visible (in other words, the set should synchronize-with the probe).
  • Once set() occurs, the next probe() will observe it. This typically requires a seq-cst ordering. See the “tickle-then-get-sleepy” scenario in the sleep README for details.

Required Methods§

source

unsafe fn set(this: *const Self)

Set the latch, signalling others.

§WARNING

Setting a latch triggers other threads to wake up and (in some cases) complete. This may, in turn, cause memory to be deallocated and so forth. One must be very careful about this, and it’s typically better to read all the fields you will need to access before a latch is set!

This function operates on *const Self instead of &self to allow it to become dangling during this call. The caller must ensure that the pointer is valid upon entry, and not invalidated during the call by any actions other than set itself.

Object Safety§

This trait is not object safe.

Implementors§