Struct Node

#[repr(transparent)]
pub struct Node {
    pub id: usize,
    /* private fields */
}

A node handle used to communicate with a thread’s reax runtime.

This is the key primitive used to implement types like Var and ComputedVar.

Although raw node ids are unique across threads, this handle does not implement Sync or Send as the runtime can only receive signals about its nodes from its own thread. Note that when this handle is dropped, the runtime will cleanup all metadata on the node.

Fields

id: usize

The unique numerical id of this node. Mostly useful for looking up node info from tables and things. Also useful for evil hacks.

Implementations

impl Node

pub fn next() -> Self

Produces a new, uniquely identified node to be managed by this thread’s runtime. Generally the runtime will not allocate table entries for this node until it has to.

pub fn computation<T>(&self, func: impl FnOnce(&ComputationHandle) -> T) -> T

Clears this node’s dependency list and rebuilds it by watching accesses made by the given function. The ComputationHandle can be used to more precisely control which accesses are included.

let a = reax::Node::next();
let b = reax::Node::next();
a.computation(|_| b.on_read());
assert!(a.depends_on(&b));

pub fn add_dependency(&self, on: &Node)

Marks the given node as a direct dependency of this node.

pub fn depends_on(&self, on: &Node) -> bool

Checks if the given node is marked as a direct dependency of this node.

pub fn num_dependencies(&self) -> usize

Returns the number of direct dependencies that this node uses.

pub fn num_dependents(&self) -> usize

Returns the number of direct dependents that use this node.

pub fn is_dirty(&self) -> bool

Returns true if a direct or indirect dependency of this node has been changed or if the node is not yet registered. Usually this can be thought of as telling whether or not the node is “outdated”. This is intended to be very cheap to call. Reset by calling on_write.

Note that a reax::Var will always appear as dirty even though it has no dependencies to make it outdated.

pub fn on_write(&self, keep_dirty: bool)

If this node is clean (or if keep_dirty is given), calling this method marks all clean downstream nodes as dirty. Otherwise, it marks this node as clean and leaves all other nodes unchanged. Any nodes transitioned from clean to dirty by this call will send notifications to their respective channels if present. This method is idempotent and generally fast to call repeatedly.

The keep_dirty flag is kinda subtle and mostly used for types like reax::Var which are supposed to remain dirty through writes but cause the dirty status to propagate to downstream nodes. In particular, this function will hang if keep_dirty is used for a node which depends on itself since the dirty flag will not be used to break the reference loop.

Lazily computed nodes should not pass keep_dirty since writes to them are assumed to bring them up-to-date (that is, clean them).

pub fn on_read(&self)

When a computation is in progress, this method generally causes self to be marked as a dependency of the actively re-computing node. See computation.

pub fn send_dirtied_signal_to(&self, handler: SharedDirtiedHandler)

Sets the object which will handle this node transitioning from clean to dirty. This is useful for quickly updating “outdated” nodes and for firing watchers. Users should be aware that dependencies of a dirtied node are not yet updated (and may panic if accessed) at the time that the handler fires. Note that a node can only be connected to one handler at a time so usage of this may interfere with utilities like EagerCompute::install.

pub fn set_label(&self, text: impl Display)

Sets the name of this node used by the runtime for debug output. This is a no-op in release mode.

pub fn from_id(id: usize) -> ManuallyDrop<Node>

Creates a node handle from a raw numerical id. Although this can’t be used to cause undefined behavior, it is a huge footgun. In particular:

• Dropping the returned node will clear all relevant runtime metadata available on the current thread.
• Runtime metadata including dependencies, dependents, labels, and dirty status will not carry over thread boundaries. If you want to share a node across threads you should find a way to sync it.

pub fn clone_id(&self) -> ManuallyDrop<Node>

Creates a copy of this node handle with all the same gotchas as from_raw.

Trait Implementations

impl Debug for Node

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Node

fn drop(&mut self)

Executes the destructor for this type.

impl Hash for Node

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Node

fn eq(&self, other: &Node) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Node

impl StructuralPartialEq for Node