Implement the component graph interface

[babeltrace.git] / include / babeltrace / component / component-graph.h

diff --git a/include/babeltrace/component/component-graph.h b/include/babeltrace/component/component-graph.h
index d87b43b9a42174edbb72ac72a09b0dc109f2a353..814218fe9817132d140dba19e52874fc5bc32f5f 100644 (file)
--- a/include/babeltrace/component/component-graph.h
+++ b/include/babeltrace/component/component-graph.h
@@ -1,10 +1,10 @@
-#ifndef BABELTRACE_COMPONENT_COMPONENT_GRAPH_H
-#define BABELTRACE_COMPONENT_COMPONENT_GRAPH_H
+#ifndef BABELTRACE_COMPONENT_GRAPH_H
+#define BABELTRACE_COMPONENT_GRAPH_H
 
 /*
- * BabelTrace - Babeltrace Component Graph Interface
+ * BabelTrace - Babeltrace Graph Interface
  *
- * Copyright 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+ * Copyright 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
  *
  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  *
@@ -27,73 +27,70 @@
  * SOFTWARE.
  */
 
-#include <babeltrace/component/component-class.h>
 #include <babeltrace/component/component.h>
-#include <babeltrace/values.h>
-#include <stdio.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-enum bt_component_graph_status {
-       BT_COMPONENT_GRAPH_STATUS_OK = 0,
-};
-
-/*
-Graph Ownership:
-
-                  Graph
-                    ^
-                    |
-               Connection
-                 ^     ^
-                /       \
-         ComponentA    ComponentB
+struct bt_port;
+struct bt_connection;
 
-1) A graph only owns a set of connections.
-2) Components should _never_ own each other.
-3) A component can keep the complete graph "alive".
+enum bt_graph_status {
+       /** Downstream component does not support multiple inputs. */
+       BT_GRAPH_STATUS_END = 1,
+       BT_GRAPH_STATUS_OK = 0,
+       /** Downstream component does not support multiple inputs. */
+       BT_GRAPH_STATUS_MULTIPLE_INPUTS_UNSUPPORTED = -1,
+       /** Component is already part of another graph. */
+       BT_GRAPH_STATUS_ALREADY_IN_A_GRAPH = -2,
+       /** Invalid arguments. */
+       BT_GRAPH_STATUS_INVALID = -3,
+       /** No sink in graph. */
+       BT_GRAPH_STATUS_NO_SINK = -4,
+       /** General error. */
+       BT_GRAPH_STATUS_ERROR = -5,
+       /** No sink can consume at the moment. */
+       BT_GRAPH_STATUS_AGAIN = -6,
+};
 
-*/
-extern struct bt_component_graph *bt_component_graph_create(void);
+extern struct bt_graph *bt_graph_create(void);
 
 /**
- * Creates a connection object which owns both components, invokes the
- * components' connection callback, and add the connection to the component
- * graph's set of connection.
- *
- * Will add any component that is not already part of the graph.
+ * Creates a connection between two components using the two ports specified
+ * and adds the connection and components (if not already added) to the graph.
  */
-extern enum bt_component_graph_status bt_component_graph_connect(
-               struct bt_component_graph *graph, struct bt_component *upstream,
-               struct bt_component *downstream);
-
-/**
- * Add component to the graph
- */
-extern enum bt_component_graph_status bt_component_graph_add_component(
-               struct bt_component_graph *graph,
-               struct bt_component *component);
+extern struct bt_connection *bt_graph_connect(struct bt_graph *graph,
+               struct bt_port *upstream,
+               struct bt_port *downstream);
 
 /**
  * Add a component as a "sibling" of the origin component. Sibling share
  * connections equivalent to each other at the time of connection (same
- * parents and children).
+ * upstream and downstream ports).
  */
-extern enum bt_component_graph_status bt_component_graph_add_component_as_sibling(
-               struct bt_component_graph *graph, struct bt_component *origin,
+extern enum bt_graph_status bt_graph_add_component_as_sibling(
+               struct bt_graph *graph, struct bt_component *origin,
                struct bt_component *new_component);
 
 /**
+ * Run graph to completion or until a single sink is left and "AGAIN" is received.
+ *
  * Runs "bt_component_sink_consume()" on all sinks in round-robin until they all
- * indicate that the end is reached on that an error occured.
+ * indicate that the end is reached or that an error occured.
+ */
+extern enum bt_graph_status bt_graph_run(struct bt_graph *graph,
+               enum bt_component_status *component_status);
+
+/**
+ * Runs "bt_component_sink_consume()" on the graph's sinks. Each invokation will
+ * invoke "bt_component_sink_consume()" on the next sink, in round-robin, until
+ * they all indicated that the end is reached.
  */
-extern enum bt_component_graph_status bt_component_graph_run(
-               struct bt_component_graph *graph);
+extern enum bt_component_status bt_graph_consume(struct bt_graph *graph);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* BABELTRACE_COMPONENT_COMPONENT_GRAPH_H */
+#endif /* BABELTRACE_COMPONENT_GRAPH_H */