Class Subgraph

A reusable subgraph that directly populates a Fragment’s operator graph.

Subgraph receives Fragment* during construction and directly adds operators and flows to the Fragment’s main graph during compose().

Usage example:

            

            
class CameraSubgraph : public Subgraph {
 public:
  CameraSubgraph(Fragment* fragment, const std::string& instance_name)
      : Subgraph(fragment, instance_name) {}

  void compose() override {
    auto source = make_operator<V4L2VideoOp>("source", from_kwargs("v4l2"));
    auto converter = make_operator<FormatConverterOp>("converter",
                                                       from_kwargs("format_converter"));

    add_flow(source, converter);  // Directly added to Fragment's main graph

    // Expose interface ports for external connections
    // The "tensor" output port of converter will be exposed as "video_out"
    add_output_interface_port("video_out", converter, "tensor");
  }
};

// In Fragment::compose():

// Note that for subgraph name "camera1" and "camera2", the operator names will become
// "camera1_source", "camera2_source", "camera1_converter", "camera2_converter".
auto camera1 = make_subgraph<CameraSubgraph>("camera1");
auto camera2 = make_subgraph<CameraSubgraph>("camera2");
auto visualizer = make_operator<HolovizOp>("visualizer", from_kwargs("holoviz"));

// Direct connection to other operators (or subgraphs) via interface ports
add_flow(camera1, visualizer, {{"video_out", "receivers"}});
add_flow(camera2, visualizer, {{"video_out", "receivers"}});
        

Public Functions

Subgraph(Fragment *fragment, const std::string &instance_name)

Construct Subgraph with target Fragment.

Parameters

• fragment – Target Fragment to populate with operators

• instance_name – Unique instance name for operator qualification

virtual ~Subgraph() = default

virtual void compose() = 0

Define the internal structure of the subgraph.

This method should create operators and flows, which will be directly added to the Fragment’s main graph with qualified names.

inline const std::string &instance_name() const

Get the instance name for this subgraph.

inline Fragment *fragment()

Get the Fragment that this subgraph belongs to.

Returns

Pointer to the fragment this subgraph belongs to

inline const Fragment *fragment() const

Get the Fragment that this subgraph belongs to (const version)

Returns

Const pointer to the fragment this subgraph belongs to

inline std::string get_qualified_name(const std::string &object_name, const std::string &type_name = "operator") const

Create qualified operator name: instance_name + “_” + operator_name.

template<typename OperatorT, typename StringT, typename ...ArgsT, typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<OperatorT> make_operator(StringT name, ArgsT&&... args)

template<typename OperatorT, typename ...ArgsT>
std::shared_ptr<OperatorT> make_operator(ArgsT&&... args)

template<typename ConditionT, typename StringT, typename ...ArgsT, typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<ConditionT> make_condition(StringT name, ArgsT&&... args)

template<typename ConditionT, typename ...ArgsT>
std::shared_ptr<ConditionT> make_condition(ArgsT&&... args)

template<typename ResourceT, typename StringT, typename ...ArgsT, typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<ResourceT> make_resource(StringT name, ArgsT&&... args)

template<typename ResourceT, typename ...ArgsT>
std::shared_ptr<ResourceT> make_resource(ArgsT&&... args)

template<typename SubgraphT, typename ...ArgsT>
inline std::shared_ptr<SubgraphT> make_subgraph(const std::string &child_instance_name, ArgsT&&... args)

Create a nested subgraph within this subgraph.

This enables hierarchical Subgraph composition. The nested Subgraph will use the same Fragment* and will have its operators added directly to the Fragment’s main graph with hierarchical qualified names (parent_instance_child_instance_operator).

Template Parameters

SubgraphT – The nested subgraph class type

Parameters

• child_instance_name – Name for the nested instance

• args – Additional arguments for the nested subgraph constructor

Returns

Shared pointer to the nested subgraph

void add_operator(std::shared_ptr<Operator> op)

Add an operator to the Fragment’s main graph with qualified name.

This directly calls fragment_->add_operator() with a qualified name, eliminating the need for intermediate graph storage.

void add_flow(const std::shared_ptr<Operator> &upstream, const std::shared_ptr<Operator> &downstream, std::set<std::pair<std::string, std::string>> port_pairs = {})

Add a flow between two operators directly in the Fragment’s main graph.

This directly calls fragment_->add_flow(), eliminating the need for intermediate flow storage.

void add_flow(const std::shared_ptr<Operator> &upstream_op, const std::shared_ptr<Subgraph> &downstream_subgraph, std::set<std::pair<std::string, std::string>> port_pairs = {})

Connect Operator to Subgraph within this Subgraph.

Parameters

• upstream_op – The upstream operator

• downstream_subgraph – The downstream subgraph

• port_pairs – Port connections: {upstream_port, subgraph_interface_port}

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Operator> &downstream_op, std::set<std::pair<std::string, std::string>> port_pairs = {})

Connect Subgraph to Operator within this Subgraph.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_op – The downstream operator

• port_pairs – Port connections: {subgraph_interface_port, downstream_port}

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Subgraph> &downstream_subgraph, std::set<std::pair<std::string, std::string>> port_pairs = {})

Connect Subgraph to Subgraph within this Subgraph.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_subgraph – The downstream subgraph

• port_pairs – Port connections: {upstream_interface_port, downstream_interface_port}

void add_flow(const std::shared_ptr<Operator> &upstream_op, const std::shared_ptr<Subgraph> &downstream_subgraph, const IOSpec::ConnectorType connector_type)

Connect Operator to Subgraph with connector type.

Parameters

• upstream_op – The upstream operator

• downstream_subgraph – The downstream subgraph

• connector_type – The connector type

void add_flow(const std::shared_ptr<Operator> &upstream_op, const std::shared_ptr<Subgraph> &downstream_subgraph, std::set<std::pair<std::string, std::string>> port_pairs, const IOSpec::ConnectorType connector_type)

Connect Operator to Subgraph with port pairs and connector type.

Parameters

• upstream_op – The upstream operator

• downstream_subgraph – The downstream subgraph

• port_pairs – Port connections: {upstream_port, subgraph_interface_port}

• connector_type – The connector type

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Operator> &downstream_op, const IOSpec::ConnectorType connector_type)

Connect Subgraph to Operator with connector type.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_op – The downstream operator

• connector_type – The connector type

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Operator> &downstream_op, std::set<std::pair<std::string, std::string>> port_pairs, const IOSpec::ConnectorType connector_type)

Connect Subgraph to Operator with port pairs and connector type.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_op – The downstream operator

• port_pairs – Port connections: {subgraph_interface_port, downstream_port}

• connector_type – The connector type

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Subgraph> &downstream_subgraph, const IOSpec::ConnectorType connector_type)

Connect Subgraph to Subgraph with connector type.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_subgraph – The downstream subgraph

• connector_type – The connector type

void add_flow(const std::shared_ptr<Subgraph> &upstream_subgraph, const std::shared_ptr<Subgraph> &downstream_subgraph, std::set<std::pair<std::string, std::string>> port_pairs, const IOSpec::ConnectorType connector_type)

Connect Subgraph to Subgraph with port pairs and connector type.

Parameters

• upstream_subgraph – The upstream subgraph

• downstream_subgraph – The downstream subgraph

• port_pairs – Port connections: {upstream_interface_port, downstream_interface_port}

• connector_type – The connector type

void add_interface_port(const std::string &external_name, const std::shared_ptr<Operator> &internal_op, const std::string &internal_port, bool is_input)

Add an interface port that can be connected from external Subgraphs/Operators.

Validates that the internal operator has the specified port and that the port type matches the expected input/output direction.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_op – The internal operator that owns the actual port

• internal_port – The port name on the internal operator

• is_input – Whether this is an input port (true) or output port (false)

void add_input_interface_port(const std::string &external_name, const std::shared_ptr<Operator> &internal_op, const std::string &internal_port)

Add an input interface port (convenience method)

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_op – The internal operator that owns the actual port

• internal_port – The port name on the internal operator

void add_output_interface_port(const std::string &external_name, const std::shared_ptr<Operator> &internal_op, const std::string &internal_port)

Add an output interface port (convenience method)

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_op – The internal operator that owns the actual port

• internal_port – The port name on the internal operator

void add_interface_port(const std::string &external_name, const std::shared_ptr<Subgraph> &internal_subgraph, const std::string &internal_interface_port, bool is_input)

Add an interface port that exposes a nested subgraph’s interface port.

This method enables hierarchical port composition by exposing an interface port from a nested subgraph as an external interface port of the current subgraph. The nested subgraph’s interface port is resolved to find the underlying operator and port, which are then registered as the current subgraph’s interface port.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_subgraph – The nested subgraph whose interface port to expose

• internal_interface_port – The interface port name on the nested subgraph

• is_input – Whether this is an input port (true) or output port (false)

void add_input_interface_port(const std::string &external_name, const std::shared_ptr<Subgraph> &internal_subgraph, const std::string &internal_interface_port)

Add an input interface port from a nested subgraph (convenience method)

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_subgraph – The nested subgraph whose interface port to expose

• internal_interface_port – The interface port name on the nested subgraph

void add_output_interface_port(const std::string &external_name, const std::shared_ptr<Subgraph> &internal_subgraph, const std::string &internal_interface_port)

Add an output interface port from a nested subgraph (convenience method)

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_subgraph – The nested subgraph whose interface port to expose

• internal_interface_port – The interface port name on the nested subgraph

void add_input_exec_interface_port(const std::string &external_name, const std::shared_ptr<Operator> &internal_op)

Add an input execution interface port for control flow.

Exposes an execution port from an internal operator for control flow connections. The internal operator must be a Native operator with an input execution spec.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_op – The internal operator that has the execution port

void add_output_exec_interface_port(const std::string &external_name, const std::shared_ptr<Operator> &internal_op)

Add an output execution interface port for control flow.

Exposes an execution port from an internal operator for control flow connections. The internal operator must be a Native operator with an output execution spec.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_op – The internal operator that has the execution port

void add_input_exec_interface_port(const std::string &external_name, const std::shared_ptr<Subgraph> &internal_subgraph, const std::string &internal_interface_port)

Add an input execution interface port from a nested subgraph.

Exposes an execution interface port from a nested subgraph as this subgraph’s execution interface port, enabling hierarchical control flow composition.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_subgraph – The nested subgraph whose exec interface port to expose

• internal_interface_port – The exec interface port name on the nested subgraph

void add_output_exec_interface_port(const std::string &external_name, const std::shared_ptr<Subgraph> &internal_subgraph, const std::string &internal_interface_port)

Add an output execution interface port from a nested subgraph.

Exposes an execution interface port from a nested subgraph as this subgraph’s execution interface port, enabling hierarchical control flow composition.

Parameters

• external_name – The name of the interface port (used in add_flow calls)

• internal_subgraph – The nested subgraph whose exec interface port to expose

• internal_interface_port – The exec interface port name on the nested subgraph

inline const std::unordered_map<std::string, InterfacePort> &interface_ports() const

Get data interface ports.

inline const std::unordered_map<std::string, InterfacePort> &exec_interface_ports() const

Get execution interface ports.

std::pair<std::shared_ptr<Operator>, std::string> get_interface_operator_port(const std::string &port_name) const

Get the operator/port for a data interface port name.

This method first checks local interface ports, then recursively checks nested subgraphs for hierarchical port resolution.

Parameters

port_name – The interface port name

Returns

Pair of (operator, actual_port_name) or (nullptr, “”) if not found

std::pair<std::shared_ptr<Operator>, std::string> get_exec_interface_operator_port(const std::string &port_name) const

Get the operator/port for an execution interface port name.

This method first checks local exec interface ports, then recursively checks nested subgraphs for hierarchical port resolution.

Parameters

port_name – The exec interface port name

Returns

Pair of (operator, actual_port_name) or (nullptr, “”) if not found

inline bool is_composed() const

Check if the subgraph has been composed.

inline void set_composed(bool composed)

Set the composed state of the subgraph.