node.hpp

Go to the documentation of this file.

#pragma once
 
// ============================================================================
//  reactive/node.hpp
// ----------------------------------------------------------------------------
//  Defines `Node` -- the core abstraction of the reactive graph.
//
//  In Aria, every entity that participates in dependency tracking
//  (Property, AutoComputed, Effect) embeds or inherits a `Node` and is
//  registered in the single process-wide DAG.
//
//  Design highlights
//  -----------------
//  1. Two-phase Push-Pull propagation. When a source changes, we only
//     recursively "color" (mark MaybeDirty) the downstream; actual
//     recomputation is deferred to batch-end / explicit flush. This is the
//     key ingredient that eliminates glitches.
//  2. Monotonic `version` per node. When a downstream node pulls from an
//     upstream, it remembers the upstream's version. On the next pull it
//     compares again and skips recomputation if nothing actually changed.
//  3. Intrusive doubly-linked edge lists. Each Edge is threaded into both
//     the source's "observers" list and the observer's "sources" list,
//     giving O(1) subscribe / unsubscribe with no heap allocation (the
//     Edge itself lives inside the observer or a dedicated pool).
//  4. Single-thread assumption. All graph mutations must happen on the UI
//     thread. Debug builds assert on thread identity at public entry
//     points. Cross-thread updates must be marshalled via a Dispatcher.
// ============================================================================
 
#include "aria/abi/export.hpp"
#include <cassert>
#include <concepts>
#include <cstdint>
#include <memory>
#include <string>
#include <thread>
#include <vector>
 
namespace aria::reactive {
 
class Node;      // forward
class Graph;     // forward
struct Edge;
 
namespace detail {

class NodeHandle {
    friend class ::aria::reactive::Node;
public:
    NodeHandle() noexcept = default;
    explicit NodeHandle(Node* node) noexcept;
    NodeHandle(const NodeHandle& other) noexcept : NodeHandle(other.node_) {}
    NodeHandle(NodeHandle&& other) noexcept;
    NodeHandle& operator=(const NodeHandle& other) noexcept;
    NodeHandle& operator=(NodeHandle&& other) noexcept;
    ~NodeHandle() { reset_(); }
 
    [[nodiscard]] Node* get() const noexcept { return node_; }
    [[nodiscard]] Node& operator*() const noexcept { return *node_; }
    [[nodiscard]] Node* operator->() const noexcept { return node_; }
    explicit operator bool() const noexcept { return node_ != nullptr; }
    friend bool operator==(const NodeHandle& a, const NodeHandle& b) noexcept {
        return a.node_ == b.node_;
    }
 
private:
    void reset_() noexcept;
    void take_(NodeHandle& other) noexcept;
    Node* node_ = nullptr;
    NodeHandle* previous_ = nullptr;
    NodeHandle* next_ = nullptr;
};
 
}  // namespace detail
 
// ---------------------------------------------------------------------------
//  Node role:
//    - Source     : an actively mutable root node (Property is a Source)
//    - Derivation : value is computed from upstreams via compute()
//                   (AutoComputed is a Derivation)
//    - Reaction   : pure side-effect node (Effect / bind callback). Its
//                   value is not exposed; it only runs an action on change.
// ---------------------------------------------------------------------------
enum class NodeKind : std::uint8_t {
    Source,
    Derivation,
    Reaction,
};
 
// ---------------------------------------------------------------------------
//  Node state during a flush cycle:
//    - Clean      : cached value matches all upstreams; pull is a no-op.
//    - MaybeDirty : an ancestor may have changed; must verify upstream
//                   versions on pull before deciding whether to recompute.
//    - Dirty      : at least one upstream has definitely changed; must
//                   recompute.
//    - Computing  : currently running compute(); used to detect cycles.
// ---------------------------------------------------------------------------
enum class NodeState : std::uint8_t {
    Clean      = 0,
    MaybeDirty = 1,
    Dirty      = 2,
    Computing  = 3,
};

struct Edge {
    Node* source   = nullptr;   
    Node* observer = nullptr;   

    Edge* next_observer = nullptr;
    Edge* prev_observer = nullptr;

    Edge* next_source = nullptr;
    Edge* prev_source = nullptr;

    std::uint64_t observed_version = 0;
};

class Node {
    // Graph is the single orchestrator of push-color / pull-evaluate and
    // therefore needs privileged access to Node's intrusive lists and
    // lifecycle state. All other code must go through the public surface.
    friend class Graph;
    friend class detail::NodeHandle;
 
public:
    explicit Node(NodeKind kind) noexcept : kind_(kind) {}
    virtual ~Node() noexcept;
 
    Node(const Node&)            = delete;
    Node& operator=(const Node&) = delete;
    Node(Node&&)                 = delete;
    Node& operator=(Node&&)      = delete;
 
    // ---- Read-only accessors ---------------------------------------------
    [[nodiscard]] NodeKind      kind()    const noexcept { return kind_; }
    [[nodiscard]] NodeState     state()   const noexcept { return state_; }
    [[nodiscard]] std::uint64_t version() const noexcept { return version_; }
    [[nodiscard]] const std::string& debug_name() const noexcept { return debug_name_; }
 
    void set_debug_name(std::string name) { debug_name_ = std::move(name); }

    [[nodiscard]] const std::string& effective_debug_name() const {
        if (!debug_name_.empty()) return debug_name_;
        if (fallback_name_.empty()) {
            const char* kind = nullptr;
            switch (kind_) {
                case NodeKind::Source:     kind = "Source";     break;
                case NodeKind::Derivation: kind = "Derivation"; break;
                case NodeKind::Reaction:   kind = "Reaction";   break;
            }
            fallback_name_ = std::string(kind ? kind : "Node")
                             + "#" + std::to_string(node_id_);
        }
        return fallback_name_;
    }

    static Graph& graph() noexcept;
 
    // ---- Methods below are intended for Graph / derived classes.          -
    // ---- They are public to simplify the implementation, not as API.      -

    void notify_changed();

    void mark_downstream_maybe_dirty();

    void mark_dirty() noexcept { state_ = NodeState::Dirty; }

    [[nodiscard]] std::uint32_t depth() const noexcept { return depth_; }
    void                         set_depth(std::uint32_t d) noexcept { depth_ = d; }

    virtual bool recompute() { return false; }

    [[nodiscard]] virtual std::shared_ptr<Node> retain_for_recompute() noexcept {
        return {};
    }
 
    // ---- Edge manipulation (intrusive linked list) -----------------------
    void attach_as_observer_of(Node& source, Edge& edge) noexcept;
    void detach_edge(Edge& edge) noexcept;

    void clear_sources() noexcept;

    template<class F>
    void for_each_observer(F&& f) {
        for (Edge* e = observers_head_; e != nullptr; e = e->next_observer) {
            f(*e);
        }
    }

    template<class F>
    void for_each_source(F&& f) const {
        for (const Edge* e = sources_head_; e != nullptr; e = e->next_source) {
            f(*e);
        }
    }
 
    [[nodiscard]] bool has_observers() const noexcept { return observers_head_ != nullptr; }
    [[nodiscard]] bool has_sources()   const noexcept { return sources_head_   != nullptr; }
 
protected:
    void retire_() noexcept;
 
    // Derived classes call this when a recompute actually changes the value.
    void bump_version_() noexcept { ++version_; }
    void set_state_(NodeState s) noexcept { state_ = s; }
 
private:
    NodeKind      kind_;
    NodeState     state_      = NodeState::Clean;
    bool          queued_     = false;
    bool          resolving_  = false;
    std::uint32_t depth_      = 0;
    std::uint64_t version_    = 1;   
 
    // Intrusive list heads. Could be made circular to drop the prev
    // pointers; kept doubly-linked for clarity of implementation.
    Edge* observers_head_ = nullptr;   
    Edge* sources_head_   = nullptr;   
    detail::NodeHandle* handles_head_ = nullptr;
 
    std::string         debug_name_;         
    mutable std::string fallback_name_;      

    std::uint64_t node_id_ = next_node_id_();
 
    ARIA_ABI_API static std::uint64_t next_node_id_() noexcept;
};
 
inline detail::NodeHandle::NodeHandle(Node* node) noexcept : node_(node) {
    if (!node_) return;
    next_ = node_->handles_head_;
    if (next_) next_->previous_ = this;
    node_->handles_head_ = this;
}
 
inline void detail::NodeHandle::reset_() noexcept {
    if (!node_) return;
    if (previous_) previous_->next_ = next_;
    else node_->handles_head_ = next_;
    if (next_) next_->previous_ = previous_;
    node_ = nullptr;
    previous_ = next_ = nullptr;
}
 
inline void detail::NodeHandle::take_(NodeHandle& other) noexcept {
    node_ = other.node_;
    previous_ = other.previous_;
    next_ = other.next_;
    if (node_) {
        if (previous_) previous_->next_ = this;
        else node_->handles_head_ = this;
        if (next_) next_->previous_ = this;
    }
    other.node_ = nullptr;
    other.previous_ = other.next_ = nullptr;
}
 
inline detail::NodeHandle::NodeHandle(NodeHandle&& other) noexcept { take_(other); }
 
inline detail::NodeHandle& detail::NodeHandle::operator=(const NodeHandle& other) noexcept {
    if (this != &other) {
        NodeHandle copy{other};
        *this = std::move(copy);
    }
    return *this;
}
 
inline detail::NodeHandle& detail::NodeHandle::operator=(NodeHandle&& other) noexcept {
    if (this != &other) {
        reset_();
        take_(other);
    }
    return *this;
}
 
}  // namespace aria::reactive
 
namespace aria {

template<typename T>
concept ReactiveNode = std::derived_from<T, ::aria::reactive::Node>;
 
}  // namespace aria