feat: added bridge node

Author: poneciak57

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/AudioGraph.hpp

@@ -166,7 +166,9 @@ inline bool AudioGraph::empty() const {
 }
 
 inline auto AudioGraph::iter() {
-  return nodes | std::views::transform([this](Node &node) {
+  return nodes |
+      std::views::filter([](const Node &n) { return n.handle->audioNode->isProcessable(); }) |
+      std::views::transform([this](Node &node) {
            return Entry{
                *node.handle->audioNode,
                pool_.view(node.input_head) |

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/BridgeNode.hpp

@@ -0,0 +1,44 @@
+#pragma once
+
+#include <audioapi/core/utils/graph/GraphObject.hpp>
+
+namespace audioapi {
+class AudioParam;
+}
+
+namespace audioapi::utils::graph {
+
+/// @brief Lightweight graph-only node that represents an AudioParam connection.
+///
+/// A BridgeNode sits between a source AudioNode and the owner AudioNode of a
+/// param, forming the path: source → bridge → owner. This lets the graph
+/// system detect cycles and compute correct topological ordering for param
+/// connections without creating real ownership dependencies.
+///
+/// BridgeNodes are:
+///   - **Not processable** — skipped by `AudioGraph::iter()`.
+///   - **Always destructible** — removed by compaction when orphaned with no inputs.
+///   - **Non-owning** — stores a raw `AudioParam*` whose lifetime is guaranteed
+///     by the owner node.
+class BridgeNode final : public GraphObject {
+ public:
+  explicit BridgeNode(AudioParam *param) : param_(param) {}
+
+  [[nodiscard]] bool isProcessable() const override {
+    return false;
+  }
+
+  [[nodiscard]] bool canBeDestructed() const override {
+    return true;
+  }
+
+  /// @brief Returns the param this bridge represents a connection to.
+  [[nodiscard]] AudioParam *param() const {
+    return param_;
+  }
+
+ private:
+  AudioParam *param_; // non-owning — lifetime guaranteed by owner node
+};
+
+} // namespace audioapi::utils::graph

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/Graph.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <audioapi/core/utils/graph/AudioGraph.hpp>
+#include <audioapi/core/utils/graph/BridgeNode.hpp>
 #include <audioapi/core/utils/graph/Disposer.hpp>
 #include <audioapi/core/utils/graph/HostGraph.hpp>
 #include <audioapi/core/utils/graph/InputPool.hpp>
@@ -13,8 +14,13 @@
 #include <algorithm>
 #include <cstdint>
 #include <memory>
+#include <unordered_map>
 #include <utility>
 
+namespace audioapi {
+class AudioParam;
+}
+
 namespace audioapi::utils::graph {
 
 /// @brief Thread-safe graph coordinator that bridges HostGraph (main thread)
@@ -165,6 +171,115 @@ class Graph {
     });
   }
 
+  // ── Param bridge API ───────────────────────────────────────────────────
+
+  /// @brief Creates a bridge node representing: source → bridge → owner.
+  ///
+  /// The bridge encodes a param connection in the graph for cycle detection
+  /// and topological ordering. The bridge itself is not processable.
+  ///
+  /// @param source the node whose output feeds the param
+  /// @param owner the node that owns the param
+  /// @param param raw pointer to the AudioParam (lifetime guaranteed by owner)
+  /// @return Ok on success, Err on cycle/duplicate/not-found
+  Res connectParam(HNode *source, HNode *owner, AudioParam *param) {
+    hostGraph.collectDisposedNodes();
+
+    BridgeKey key{source, param};
+    if (bridgeMap_.count(key)) {
+      return Res::Err(ResultError::EDGE_ALREADY_EXISTS);
+    }
+
+    // Create bridge node
+    auto bridgeObj = std::make_unique<BridgeNode>(param);
+    auto bridgeHandle = std::make_shared<NodeHandle>(0, std::move(bridgeObj));
+    auto [bridgeHostNode, addEvent] = hostGraph.addNode(bridgeHandle);
+
+    // source → bridge
+    auto edgeRes1 = hostGraph.addEdge(source, bridgeHostNode);
+    if (edgeRes1.is_err()) {
+      // Rollback: remove bridge node
+      (void)hostGraph.removeNode(bridgeHostNode);
+      return Res::Err(edgeRes1.unwrap_err());
+    }
+
+    // bridge → owner
+    auto edgeRes2 = hostGraph.addEdge(bridgeHostNode, owner);
+    if (edgeRes2.is_err()) {
+      // Rollback: remove source→bridge edge and bridge node
+      (void)hostGraph.removeEdge(source, bridgeHostNode);
+      (void)hostGraph.removeNode(bridgeHostNode);
+      return Res::Err(edgeRes2.unwrap_err());
+    }
+
+    // All succeeded — send events through SPSC
+    sendNodeGrowIfNeeded();
+    eventSender_.send(std::move(addEvent));
+
+    sendPoolGrowIfNeeded();
+    eventSender_.send(std::move(edgeRes1).unwrap());
+
+    sendPoolGrowIfNeeded();
+    eventSender_.send(std::move(edgeRes2).unwrap());
+
+    // Track bridge
+    bridgeMap_[key] = bridgeHostNode;
+    bridgeOwners_[bridgeHostNode] = owner;
+
+    return Res::Ok(NoneType{});
+  }
+
+  /// @brief Removes a bridge node for the given (source, param) pair.
+  Res disconnectParam(HNode *source, HNode * /*owner*/, AudioParam *param) {
+    hostGraph.collectDisposedNodes();
+
+    BridgeKey key{source, param};
+    auto it = bridgeMap_.find(key);
+    if (it == bridgeMap_.end()) {
+      return Res::Err(ResultError::EDGE_NOT_FOUND);
+    }
+
+    HNode *bridge = it->second;
+    removeBridge(source, bridge);
+    bridgeMap_.erase(it);
+
+    return Res::Ok(NoneType{});
+  }
+
+  /// @brief Removes a node and cascade-removes any bridges where this node
+  /// is the source or owner.
+  Res removeNodeWithBridges(HNode *node) {
+    hostGraph.collectDisposedNodes();
+
+    // Cascade: remove bridges where this node is source
+    for (auto it = bridgeMap_.begin(); it != bridgeMap_.end();) {
+      if (it->first.source == node) {
+        HNode *bridge = it->second;
+        removeBridge(node, bridge);
+        bridgeOwners_.erase(bridge);
+        it = bridgeMap_.erase(it);
+      } else {
+        ++it;
+      }
+    }
+
+    // Cascade: remove bridges where this node is owner
+    for (auto it = bridgeMap_.begin(); it != bridgeMap_.end();) {
+      auto ownerIt = bridgeOwners_.find(it->second);
+      if (ownerIt != bridgeOwners_.end() && ownerIt->second == node) {
+        HNode *bridge = it->second;
+        HNode *source = it->first.source;
+        removeBridge(source, bridge);
+        bridgeOwners_.erase(ownerIt);
+        it = bridgeMap_.erase(it);
+      } else {
+        ++it;
+      }
+    }
+
+    return removeNode(node);
+  }
+
  private:
   static constexpr size_t kDisposerPayloadSize = HostGraph::kDisposerPayloadSize;
 
@@ -223,6 +338,57 @@ class Graph {
     }
   }
 
+  // ── Bridge tracking (main thread only) ──────────────────────────────────
+
+  struct BridgeKey {
+    HNode *source;
+    AudioParam *param;
+
+    bool operator==(const BridgeKey &other) const {
+      return source == other.source && param == other.param;
+    }
+  };
+
+  struct BridgeKeyHash {
+    size_t operator()(const BridgeKey &k) const {
+      auto h1 = std::hash<HNode *>{}(k.source);
+      auto h2 = std::hash<AudioParam *>{}(k.param);
+      return h1 ^ (h2 << 1);
+    }
+  };
+
+  /// Maps (source, param) → bridge host node
+  std::unordered_map<BridgeKey, HNode *, BridgeKeyHash> bridgeMap_;
+
+  /// Maps bridge host node → owner host node (for cascade removal)
+  std::unordered_map<HNode *, HNode *> bridgeOwners_;
+
+  /// @brief Removes a bridge node: tears down edges and marks for removal.
+  void removeBridge(HNode *source, HNode *bridge) {
+    // Find the owner from bridgeOwners_
+    auto ownerIt = bridgeOwners_.find(bridge);
+    HNode *owner = (ownerIt != bridgeOwners_.end()) ? ownerIt->second : nullptr;
+
+    // Remove edges: source→bridge, bridge→owner
+    auto res1 = hostGraph.removeEdge(source, bridge);
+    if (res1.is_ok()) {
+      eventSender_.send(std::move(res1).unwrap());
+    }
+
+    if (owner) {
+      auto res2 = hostGraph.removeEdge(bridge, owner);
+      if (res2.is_ok()) {
+        eventSender_.send(std::move(res2).unwrap());
+      }
+    }
+
+    // Remove bridge node
+    auto res3 = hostGraph.removeNode(bridge);
+    if (res3.is_ok()) {
+      eventSender_.send(std::move(res3).unwrap());
+    }
+  }
+
   friend class GraphTest;
 };
 

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/GraphObject.hpp

@@ -30,6 +30,15 @@ class GraphObject {
     return true;
   }
 
+  /// @brief Returns whether this node should be processed during audio iteration.
+  ///
+  /// Default is true. BridgeNodes override to return false — they exist only
+  /// for graph structure (cycle detection, topo ordering) and are skipped
+  /// by AudioGraph::iter().
+  [[nodiscard]] virtual bool isProcessable() const {
+    return true;
+  }
+
   /// @brief Downcast helper for node-specific handling.
   [[nodiscard]] virtual AudioNode *asAudioNode() {
     return nullptr;

packages/react-native-audio-api/common/cpp/audioapi/core/utils/graph/HostNode.hpp

@@ -103,6 +103,18 @@ class HostNode {
     return graph_->removeEdge(node_, other.node_);
   }
 
+  /// @brief Connects this node's output to a param on the owner node via a bridge.
+  /// @return Ok on success, Err on cycle / duplicate / not-found
+  Res connectParam(HostNode &owner, AudioParam *param) {
+    return graph_->connectParam(node_, owner.node_, param);
+  }
+
+  /// @brief Disconnects this node's output from a param on the owner node.
+  /// @return Ok on success, Err on not-found
+  Res disconnectParam(HostNode &owner, AudioParam *param) {
+    return graph_->disconnectParam(node_, owner.node_, param);
+  }
+
   /// @brief Returns the raw HostGraph::Node pointer (for advanced usage / testing).
   [[nodiscard]] HNode *rawNode() const {
     return node_;