src/lib/graph/graph.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
   5  * Copyright 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   6  */
   7
   8 #ifndef BABELTRACE_GRAPH_GRAPH_INTERNAL_H
   9 #define BABELTRACE_GRAPH_GRAPH_INTERNAL_H
  10
  11 /* Protection: this file uses BT_LIB_LOG*() macros directly */
  12 #ifndef BT_LIB_LOG_SUPPORTED
  13 # error Please include "lib/logging.h" before including this file.
  14 #endif
  15
  16 #include <babeltrace2/graph/graph.h>
  17 #include <babeltrace2/graph/message.h>
  18 #include "common/macros.h"
  19 #include "lib/object.h"
  20 #include "lib/object-pool.h"
  21 #include "common/assert.h"
  22 #include "common/common.h"
  23 #include <stdbool.h>
  24 #include <stdlib.h>
  25 #include <glib.h>
  26
  27 #include "component.h"
  28 #include "component-sink.h"
  29 #include "connection.h"
  30 #include "lib/func-status.h"
  31
  32 /* Protection: this file uses BT_LIB_LOG*() macros directly */
  33 #ifndef BT_LIB_LOG_SUPPORTED
  34 # error Please include "lib/logging.h" before including this file.
  35 #endif
  36
  37 /*
  38  * Protection: this file uses precondition and postcondition assertion
  39  * macros directly.
  40  */
  41 #ifndef BT_ASSERT_COND_SUPPORTED
  42 # error Please include "lib/assert-cond.h" before including this file.
  43 #endif
  44
  45 struct bt_component;
  46 struct bt_port;
  47
  48 enum bt_graph_configuration_state {
  49         BT_GRAPH_CONFIGURATION_STATE_CONFIGURING,
  50         BT_GRAPH_CONFIGURATION_STATE_PARTIALLY_CONFIGURED,
  51         BT_GRAPH_CONFIGURATION_STATE_CONFIGURED,
  52         BT_GRAPH_CONFIGURATION_STATE_FAULTY,
  53         BT_GRAPH_CONFIGURATION_STATE_DESTROYING,
  54 };
  55
  56 struct bt_graph {
  57         /**
  58          * A component graph contains components and point-to-point connection
  59          * between these components.
  60          *
  61          * In terms of ownership:
  62          * 1) The graph is the components' parent,
  63          * 2) The graph is the connnections' parent,
  64          * 3) Components share the ownership of their connections,
  65          * 4) A connection holds weak references to its two component endpoints.
  66          */
  67         struct bt_object base;
  68
  69         /* Array of pointers to bt_connection. */
  70         GPtrArray *connections;
  71         /* Array of pointers to bt_component. */
  72         GPtrArray *components;
  73         /* Queue of pointers (weak references) to sink bt_components. */
  74         GQueue *sinks_to_consume;
  75
  76         uint64_t mip_version;
  77
  78         /*
  79          * Array of `struct bt_interrupter *`, each one owned by this.
  80          * If any interrupter is set, then this graph is deemed
  81          * interrupted.
  82          */
  83         GPtrArray *interrupters;
  84
  85         /*
  86          * Default interrupter, owned by this.
  87          */
  88         struct bt_interrupter *default_interrupter;
  89
  90         bool has_sink;
  91
  92         /*
  93          * If this is false, then the public API's consuming
  94          * functions (bt_graph_consume() and bt_graph_run()) return
  95          * BT_FUNC_STATUS_CANNOT_CONSUME. The internal "no check"
  96          * functions always work.
  97          *
  98          * In bt_port_output_message_iterator_create(), on success,
  99          * this flag is cleared so that the iterator remains the only
 100          * consumer for the graph's lifetime.
 101          */
 102         bool can_consume;
 103
 104         enum bt_graph_configuration_state config_state;
 105
 106         struct {
 107                 GArray *source_output_port_added;
 108                 GArray *filter_output_port_added;
 109                 GArray *filter_input_port_added;
 110                 GArray *sink_input_port_added;
 111         } listeners;
 112
 113         /* Pool of `struct bt_message_event *` */
 114         struct bt_object_pool event_msg_pool;
 115
 116         /* Pool of `struct bt_message_packet_beginning *` */
 117         struct bt_object_pool packet_begin_msg_pool;
 118
 119         /* Pool of `struct bt_message_packet_end *` */
 120         struct bt_object_pool packet_end_msg_pool;
 121
 122         /*
 123          * Array of `struct bt_message *` (weak).
 124          *
 125          * This is an array of all the messages ever created from
 126          * this graph. Some of them can be in one of the pools above,
 127          * some of them can be at large. Because each message has a
 128          * weak pointer to the graph containing its pool, we need to
 129          * notify each message that the graph is gone on graph
 130          * destruction.
 131          *
 132          * TODO: When we support a maximum size for object pools,
 133          * add a way for a message to remove itself from this
 134          * array (on destruction).
 135          */
 136         GPtrArray *messages;
 137 };
 138
 139 static inline
 140 void bt_graph_set_can_consume(struct bt_graph *graph, bool can_consume)
 141 {
 142         BT_ASSERT_DBG(graph);
 143         graph->can_consume = can_consume;
 144 }
 145
 146 BT_HIDDEN
 147 int bt_graph_consume_sink_no_check(struct bt_graph *graph,
 148                 struct bt_component_sink *sink);
 149
 150 BT_HIDDEN
 151 enum bt_graph_listener_func_status bt_graph_notify_port_added(struct bt_graph *graph,
 152                 struct bt_port *port);
 153
 154 BT_HIDDEN
 155 void bt_graph_remove_connection(struct bt_graph *graph,
 156                 struct bt_connection *connection);
 157
 158 BT_HIDDEN
 159 void bt_graph_add_message(struct bt_graph *graph,
 160                 struct bt_message *msg);
 161
 162 BT_HIDDEN
 163 bool bt_graph_is_interrupted(const struct bt_graph *graph);
 164
 165 static inline
 166 const char *bt_graph_configuration_state_string(
 167                 enum bt_graph_configuration_state state)
 168 {
 169         switch (state) {
 170         case BT_GRAPH_CONFIGURATION_STATE_CONFIGURING:
 171                 return "CONFIGURING";
 172         case BT_GRAPH_CONFIGURATION_STATE_PARTIALLY_CONFIGURED:
 173                 return "PARTIALLY_CONFIGURED";
 174         case BT_GRAPH_CONFIGURATION_STATE_CONFIGURED:
 175                 return "CONFIGURED";
 176         case BT_GRAPH_CONFIGURATION_STATE_FAULTY:
 177                 return "FAULTY";
 178         case BT_GRAPH_CONFIGURATION_STATE_DESTROYING:
 179                 return "DESTROYING";
 180         default:
 181                 return "(unknown)";
 182         }
 183 }
 184
 185 static inline
 186 int bt_graph_configure(struct bt_graph *graph)
 187 {
 188         int status = BT_FUNC_STATUS_OK;
 189         uint64_t i;
 190
 191         BT_ASSERT_DBG(graph->config_state !=
 192                 BT_GRAPH_CONFIGURATION_STATE_FAULTY);
 193
 194         if (G_LIKELY(graph->config_state ==
 195                         BT_GRAPH_CONFIGURATION_STATE_CONFIGURED)) {
 196                 goto end;
 197         }
 198
 199         BT_ASSERT_PRE(graph->has_sink, "Graph has no sink component: %!+g", graph);
 200         graph->config_state = BT_GRAPH_CONFIGURATION_STATE_PARTIALLY_CONFIGURED;
 201
 202         for (i = 0; i < graph->components->len; i++) {
 203                 struct bt_component *comp = graph->components->pdata[i];
 204                 struct bt_component_sink *comp_sink = (void *) comp;
 205                 struct bt_component_class_sink *comp_cls_sink =
 206                         (void *) comp->class;
 207
 208                 if (comp->class->type != BT_COMPONENT_CLASS_TYPE_SINK) {
 209                         continue;
 210                 }
 211
 212                 if (comp_sink->graph_is_configured_method_called) {
 213                         continue;
 214                 }
 215
 216                 if (comp_cls_sink->methods.graph_is_configured) {
 217                         enum bt_component_class_sink_graph_is_configured_method_status comp_status;
 218
 219                         BT_LIB_LOGD("Calling user's \"graph is configured\" method: "
 220                                 "%![graph-]+g, %![comp-]+c",
 221                                 graph, comp);
 222                         comp_status = comp_cls_sink->methods.graph_is_configured(
 223                                 (void *) comp_sink);
 224                         BT_LIB_LOGD("User method returned: status=%s",
 225                                 bt_common_func_status_string(comp_status));
 226                         BT_ASSERT_POST(comp_status == BT_FUNC_STATUS_OK ||
 227                                 comp_status == BT_FUNC_STATUS_ERROR ||
 228                                 comp_status == BT_FUNC_STATUS_MEMORY_ERROR,
 229                                 "Unexpected returned status: status=%s",
 230                                 bt_common_func_status_string(comp_status));
 231                         BT_ASSERT_POST_NO_ERROR_IF_NO_ERROR_STATUS(comp_status);
 232                         if (comp_status != BT_FUNC_STATUS_OK) {
 233                                 if (comp_status < 0) {
 234                                         BT_LIB_LOGW_APPEND_CAUSE(
 235                                                 "Component's \"graph is configured\" method failed: "
 236                                                 "%![comp-]+c, status=%s",
 237                                                 comp,
 238                                                 bt_common_func_status_string(
 239                                                         comp_status));
 240                                 }
 241
 242                                 status = comp_status;
 243                                 goto end;
 244                         }
 245                 }
 246
 247                 comp_sink->graph_is_configured_method_called = true;
 248         }
 249
 250         graph->config_state = BT_GRAPH_CONFIGURATION_STATE_CONFIGURED;
 251
 252 end:
 253         return status;
 254 }
 255
 256 static inline
 257 void bt_graph_make_faulty(struct bt_graph *graph)
 258 {
 259         graph->config_state = BT_GRAPH_CONFIGURATION_STATE_FAULTY;
 260         BT_LIB_LOGI("Set graph's state to faulty: %![graph-]+g", graph);
 261 }
 262
 263 #endif /* BABELTRACE_GRAPH_GRAPH_INTERNAL_H */