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