Document libbabeltrace2's C API
[babeltrace.git] / src / lib / graph / query-executor.c
CommitLineData
c7eee084 1/*
e2f7325d 2 * Copyright 2017-2018 Philippe Proulx <pproulx@efficios.com>
c7eee084
PP
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 * SOFTWARE.
21 */
22
350ad6c1 23#define BT_LOG_TAG "LIB/QUERY-EXECUTOR"
c2d9d9cf 24#include "lib/logging.h"
c7eee084 25
578e048b 26#include "common/assert.h"
f4e38e70 27#include "common/common.h"
578e048b 28#include "lib/assert-pre.h"
f6f301d7 29#include "lib/assert-post.h"
3fadfbc0 30#include <babeltrace2/graph/query-executor.h>
3fadfbc0 31#include <babeltrace2/graph/component-class.h>
43c59509 32#include <babeltrace2/graph/query-executor.h>
3fadfbc0 33#include <babeltrace2/value.h>
578e048b
MJ
34#include "lib/object.h"
35#include "compat/compiler.h"
36
37#include "component-class.h"
38#include "query-executor.h"
9b4f9b42 39#include "interrupter.h"
d24d5663 40#include "lib/func-status.h"
c7eee084
PP
41
42static
43void bt_query_executor_destroy(struct bt_object *obj)
44{
45 struct bt_query_executor *query_exec =
46 container_of(obj, struct bt_query_executor, base);
47
d94d92ac 48 BT_LOGD("Destroying query executor: addr=%p", query_exec);
9b4f9b42
PP
49
50 if (query_exec->interrupters) {
51 BT_LOGD_STR("Putting interrupters.");
52 g_ptr_array_free(query_exec->interrupters, TRUE);
53 query_exec->interrupters = NULL;
54 }
55
3c729b9a
PP
56 BT_LOGD_STR("Putting component class.");
57 BT_OBJECT_PUT_REF_AND_RESET(query_exec->comp_cls);
58
59 if (query_exec->object) {
60 g_string_free(query_exec->object, TRUE);
61 query_exec->object = NULL;
62 }
9b4f9b42 63
3c729b9a
PP
64 BT_LOGD_STR("Putting parameters.");
65 BT_OBJECT_PUT_REF_AND_RESET(query_exec->params);
66 BT_OBJECT_PUT_REF_AND_RESET(query_exec->default_interrupter);
c7eee084
PP
67 g_free(query_exec);
68}
69
7c14d641 70struct bt_query_executor *bt_query_executor_create_with_method_data(
3c729b9a 71 const bt_component_class *comp_cls, const char *object,
7c14d641 72 const bt_value *params, void *method_data)
c7eee084
PP
73{
74 struct bt_query_executor *query_exec;
75
17f3083a 76 BT_ASSERT_PRE_NO_ERROR();
3c729b9a
PP
77 BT_ASSERT_PRE_NON_NULL(comp_cls, "Component class");
78 BT_ASSERT_PRE_NON_NULL(object, "Object");
79 BT_LIB_LOGD("Creating query executor: "
fb739d29 80 "%![comp-cls-]+C, object=\"%s\", %![params-]+v",
3c729b9a 81 comp_cls, object, params);
c7eee084
PP
82 query_exec = g_new0(struct bt_query_executor, 1);
83 if (!query_exec) {
870631a2
PP
84 BT_LIB_LOGE_APPEND_CAUSE(
85 "Failed to allocate one query executor.");
c7eee084
PP
86 goto end;
87 }
88
9b4f9b42 89 query_exec->interrupters = g_ptr_array_new_with_free_func(
6871026b 90 (GDestroyNotify) bt_object_put_ref_no_null_check);
9b4f9b42
PP
91 if (!query_exec->interrupters) {
92 BT_LIB_LOGE_APPEND_CAUSE("Failed to allocate one GPtrArray.");
93 BT_OBJECT_PUT_REF_AND_RESET(query_exec);
94 goto end;
95 }
96
97 query_exec->default_interrupter = bt_interrupter_create();
98 if (!query_exec->default_interrupter) {
99 BT_LIB_LOGE_APPEND_CAUSE(
100 "Failed to create one interrupter object.");
101 BT_OBJECT_PUT_REF_AND_RESET(query_exec);
102 goto end;
103 }
104
3c729b9a
PP
105 query_exec->object = g_string_new(object);
106 if (!query_exec->object) {
107 BT_LIB_LOGE_APPEND_CAUSE("Failed to allocate one GString.");
108 BT_OBJECT_PUT_REF_AND_RESET(query_exec);
109 goto end;
110 }
111
112 query_exec->comp_cls = comp_cls;
6871026b 113 bt_object_get_ref_no_null_check(query_exec->comp_cls);
3c729b9a
PP
114
115 if (!params) {
116 query_exec->params = bt_value_null;
117 } else {
118 query_exec->params = params;
119 }
120
6871026b 121 bt_object_get_ref_no_null_check(query_exec->params);
7c14d641 122 query_exec->method_data = method_data;
3c729b9a 123 query_exec->log_level = BT_LOGGING_LEVEL_NONE;
9b4f9b42
PP
124 bt_query_executor_add_interrupter(query_exec,
125 query_exec->default_interrupter);
3fea54f6
PP
126 bt_object_init_shared(&query_exec->base,
127 bt_query_executor_destroy);
3c729b9a 128 BT_LIB_LOGD("Created query executor: "
fb739d29 129 "addr=%p, %![comp-cls-]+C, object=\"%s\", %![params-]+v",
3c729b9a 130 query_exec, comp_cls, object, params);
c7eee084
PP
131
132end:
d94d92ac 133 return (void *) query_exec;
c7eee084
PP
134}
135
7c14d641
PP
136struct bt_query_executor *bt_query_executor_create(
137 const bt_component_class *comp_cls, const char *object,
138 const bt_value *params)
139{
17f3083a 140 BT_ASSERT_PRE_NO_ERROR();
7c14d641
PP
141 return bt_query_executor_create_with_method_data(comp_cls,
142 object, params, NULL);
143}
144
d24d5663 145enum bt_query_executor_query_status bt_query_executor_query(
0d72b8c3 146 struct bt_query_executor *query_exec,
05e21286 147 const struct bt_value **user_result)
c7eee084 148{
3c729b9a
PP
149 typedef enum bt_component_class_query_method_status (*method_t)(
150 void * /* self component class */,
151 void * /* private query executor */,
152 const char * /* object */,
153 const struct bt_value * /* parameters */,
7c14d641 154 void * /* method data */,
3c729b9a 155 const struct bt_value ** /* result */);
c7eee084 156
d24d5663
PP
157 enum bt_query_executor_query_status status;
158 enum bt_component_class_query_method_status query_status;
d94d92ac 159 method_t method = NULL;
c7eee084 160
17f3083a 161 BT_ASSERT_PRE_NO_ERROR();
d94d92ac 162 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
d94d92ac 163 BT_ASSERT_PRE_NON_NULL(user_result, "Result (output)");
d94d92ac 164
647c6d45
PP
165 /*
166 * Initial check: is the query executor already interrupted? If
167 * so, return `BT_FUNC_STATUS_AGAIN`. Returning this status is
168 * harmless: it's not `BT_FUNC_STATUS_OK` (there's no result),
169 * and it's not `BT_FUNC_STATUS_ERROR` either (there's no
170 * legitimate error). Since any query operation could return
171 * `BT_FUNC_STATUS_AGAIN` when interrupted or instead of
172 * blocking, the caller is responsible for checking the
173 * interruption state of the query executor when getting this
174 * status.
175 */
176 if (bt_query_executor_is_interrupted(query_exec)) {
177 BT_LIB_LOGD("Query executor is interrupted: "
178 "not performing the query operation: "
179 "query-exec-addr=%p, %![cc-]+C, object=\"%s\", "
180 "%![params-]+v, log-level=%s",
3c729b9a
PP
181 query_exec, query_exec->comp_cls,
182 query_exec->object->str, query_exec->params,
183 bt_common_logging_level_string(query_exec->log_level));
647c6d45
PP
184 status = BT_FUNC_STATUS_AGAIN;
185 goto end;
186 }
187
3c729b9a 188 switch (query_exec->comp_cls->type) {
d94d92ac
PP
189 case BT_COMPONENT_CLASS_TYPE_SOURCE:
190 {
3c729b9a
PP
191 struct bt_component_class_source *src_cc = (void *)
192 query_exec->comp_cls;
d94d92ac
PP
193
194 method = (method_t) src_cc->methods.query;
195 break;
c7eee084 196 }
d94d92ac
PP
197 case BT_COMPONENT_CLASS_TYPE_FILTER:
198 {
3c729b9a
PP
199 struct bt_component_class_filter *flt_cc = (void *)
200 query_exec->comp_cls;
c7eee084 201
d94d92ac
PP
202 method = (method_t) flt_cc->methods.query;
203 break;
c7eee084 204 }
d94d92ac
PP
205 case BT_COMPONENT_CLASS_TYPE_SINK:
206 {
3c729b9a
PP
207 struct bt_component_class_sink *sink_cc = (void *)
208 query_exec->comp_cls;
c7eee084 209
d94d92ac
PP
210 method = (method_t) sink_cc->methods.query;
211 break;
212 }
213 default:
498e7994 214 bt_common_abort();
c7eee084
PP
215 }
216
d94d92ac 217 if (!method) {
c7eee084 218 /* Not an error: nothing to query */
d94d92ac 219 BT_LIB_LOGD("Component class has no registered query method: "
3c729b9a 220 "%!+C", query_exec->comp_cls);
76b6c2f7 221 status = BT_FUNC_STATUS_UNKNOWN_OBJECT;
c7eee084
PP
222 goto end;
223 }
224
d94d92ac 225 BT_LIB_LOGD("Calling user's query method: "
f4e38e70
PP
226 "query-exec-addr=%p, %![cc-]+C, object=\"%s\", %![params-]+v, "
227 "log-level=%s",
3c729b9a
PP
228 query_exec, query_exec->comp_cls, query_exec->object->str,
229 query_exec->params,
230 bt_common_logging_level_string(query_exec->log_level));
d94d92ac 231 *user_result = NULL;
3c729b9a
PP
232 query_status = method((void *) query_exec->comp_cls,
233 (void *) query_exec, query_exec->object->str,
7c14d641 234 query_exec->params, query_exec->method_data, user_result);
d94d92ac 235 BT_LIB_LOGD("User method returned: status=%s, %![res-]+v",
d24d5663
PP
236 bt_common_func_status_string(query_status), *user_result);
237 BT_ASSERT_POST(query_status != BT_FUNC_STATUS_OK || *user_result,
238 "User method returned `BT_FUNC_STATUS_OK` without a result.");
6ecdcca3 239 BT_ASSERT_POST_NO_ERROR_IF_NO_ERROR_STATUS(query_status);
d24d5663 240 status = (int) query_status;
c7eee084 241
a635e507
SM
242 if (status < 0) {
243 BT_LIB_LOGW_APPEND_CAUSE(
244 "Component class's \"query\" method failed: "
245 "query-exec-addr=%p, %![cc-]+C, object=\"%s\", "
3c729b9a
PP
246 "%![params-]+v, log-level=%s", query_exec,
247 query_exec->comp_cls, query_exec->object->str,
248 query_exec->params,
249 bt_common_logging_level_string(query_exec->log_level));
a635e507
SM
250 goto end;
251 }
252
c7eee084 253end:
d24d5663 254 return status;
c7eee084
PP
255}
256
9b4f9b42
PP
257enum bt_query_executor_add_interrupter_status bt_query_executor_add_interrupter(
258 struct bt_query_executor *query_exec,
259 const struct bt_interrupter *intr)
c7eee084 260{
17f3083a 261 BT_ASSERT_PRE_NO_ERROR();
d94d92ac 262 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
9b4f9b42
PP
263 BT_ASSERT_PRE_NON_NULL(intr, "Interrupter");
264 g_ptr_array_add(query_exec->interrupters, (void *) intr);
6871026b 265 bt_object_get_ref_no_null_check(intr);
9b4f9b42
PP
266 BT_LIB_LOGD("Added interrupter to query executor: "
267 "query-exec-addr=%p, %![intr-]+z",
268 query_exec, intr);
d24d5663 269 return BT_FUNC_STATUS_OK;
c7eee084
PP
270}
271
9b4f9b42 272bt_bool bt_query_executor_is_interrupted(const struct bt_query_executor *query_exec)
c7eee084 273{
9b4f9b42
PP
274 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
275 return (bt_bool) bt_interrupter_array_any_is_set(
276 query_exec->interrupters);
277}
278
88d1a0b7
SM
279struct bt_interrupter *bt_query_executor_borrow_default_interrupter(
280 struct bt_query_executor *query_exec)
9b4f9b42
PP
281{
282 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
88d1a0b7 283 return query_exec->default_interrupter;
c7eee084 284}
c5b9b441 285
3c729b9a
PP
286enum bt_query_executor_set_logging_level_status
287bt_query_executor_set_logging_level(struct bt_query_executor *query_exec,
288 enum bt_logging_level log_level)
289{
290 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
291 query_exec->log_level = log_level;
292 return BT_FUNC_STATUS_OK;
293}
294
295enum bt_logging_level bt_query_executor_get_logging_level(
296 const struct bt_query_executor *query_exec)
297{
298 BT_ASSERT_PRE_NON_NULL(query_exec, "Query executor");
299 return query_exec->log_level;
300}
301
c5b9b441
PP
302void bt_query_executor_get_ref(const struct bt_query_executor *query_executor)
303{
304 bt_object_get_ref(query_executor);
305}
306
307void bt_query_executor_put_ref(const struct bt_query_executor *query_executor)
308{
309 bt_object_put_ref(query_executor);
310}
This page took 0.070568 seconds and 4 git commands to generate.