Commit | Line | Data |
---|---|---|
347829f5 PP |
1 | #ifndef _BABELTRACE_OBJECTS_H |
2 | #define _BABELTRACE_OBJECTS_H | |
3 | ||
4 | /* | |
5 | * Babeltrace | |
6 | * | |
7 | * Basic object system | |
8 | * | |
9 | * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation | |
10 | * Copyright (c) 2015 Philippe Proulx <pproulx@efficios.com> | |
11 | * | |
12 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
13 | * of this software and associated documentation files (the "Software"), to deal | |
14 | * in the Software without restriction, including without limitation the rights | |
15 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
16 | * copies of the Software, and to permit persons to whom the Software is | |
17 | * furnished to do so, subject to the following conditions: | |
18 | * | |
19 | * The above copyright notice and this permission notice shall be included in | |
20 | * all copies or substantial portions of the Software. | |
21 | * | |
22 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
23 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
24 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
25 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
26 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
27 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
28 | * SOFTWARE. | |
29 | */ | |
30 | ||
31 | /** | |
32 | * @file objects.h | |
33 | * @brief Basic object system | |
34 | * | |
35 | * This is a basic object system API. The following functions allow you | |
36 | * to create, modify, and destroy: | |
37 | * | |
38 | * - \link bt_object_null null objects\endlink | |
39 | * - \link bt_object_bool_create() boolean objects\endlink | |
40 | * - \link bt_object_integer_create() integer objects\endlink | |
41 | * - \link bt_object_float_create() floating point number | |
42 | * objects\endlink | |
43 | * - \link bt_object_string_create() string objects\endlink | |
44 | * - \link bt_object_array_create() array objects\endlink, | |
45 | * containing zero or more objects | |
46 | * - \link bt_object_map_create() map objects\endlink, mapping | |
47 | * string keys to objects | |
48 | * | |
49 | * All the object types above, except for null objects (which always | |
50 | * point to the same \link bt_object_null singleton\endlink), have a | |
51 | * reference count property. Once an object is created, its reference | |
52 | * count is set to 1. When \link bt_object_array_append() appending an | |
53 | * object to an array object\endlink, or \link bt_object_map_insert() | |
54 | * inserting an object into a map object\endlink, its reference count | |
55 | * is incremented, as well as when getting an object back from those | |
56 | * structures. The bt_object_get() and bt_object_put() functions exist | |
57 | * to deal with reference counting. Once you are done with an object, | |
58 | * pass it to bt_object_put(). | |
59 | * | |
60 | * A common action with objects is to create or get one, do something | |
61 | * with it, and then put it. To avoid putting it a second time later | |
62 | * (if an error occurs, for example), the variable is often reset to | |
63 | * \c NULL after putting the object it points to. Since this is so | |
64 | * common, you can use the BT_OBJECT_PUT() macro, which does just that: | |
65 | * | |
66 | * \code{.c} | |
67 | * struct bt_object *int_obj = bt_object_integer_create_init(34); | |
68 | * | |
69 | * if (!int_obj) { | |
70 | * goto error; | |
71 | * } | |
72 | * | |
73 | * // stuff, which could jump to error | |
74 | * | |
75 | * BT_OBJECT_PUT(int_obj); | |
76 | * | |
77 | * // stuff, which could jump to error | |
78 | * | |
79 | * return 0; | |
80 | * | |
81 | * error: | |
82 | * // safe, even if int_obj is NULL | |
83 | * BT_OBJECT_PUT(int_obj); | |
a40a567e PP |
84 | * |
85 | * // ... | |
347829f5 PP |
86 | * \endcode |
87 | * | |
88 | * Another common manipulation is to move the ownership of an object | |
89 | * from one variable to another: since the reference count is not | |
90 | * incremented, and since, to avoid errors, two variables should not | |
91 | * point to same object without each of them having their own reference, | |
92 | * it is best practice to set the original variable to \c NULL. This | |
93 | * too can be accomplished in a single step using the BT_OBJECT_MOVE() | |
94 | * macro: | |
95 | * | |
96 | * \code{.c} | |
97 | * struct bt_object *int_obj2 = NULL; | |
98 | * struct bt_object *int_obj = bt_object_integer_create_init(-23); | |
99 | * | |
100 | * if (!int_obj) { | |
101 | * goto error; | |
102 | * } | |
103 | * | |
104 | * // stuff, which could jump to error | |
105 | * | |
106 | * BT_OBJECT_MOVE(int_obj2, int_obj); | |
107 | * | |
108 | * // stuff, which could jump to error | |
109 | * | |
110 | * return 0; | |
111 | * | |
112 | * error: | |
113 | * // safe, since only one of int_obj/int_obj2 (or none) | |
114 | * // points to the object | |
115 | * BT_OBJECT_PUT(int_obj); | |
116 | * BT_OBJECT_PUT(int_obj2); | |
a40a567e PP |
117 | * |
118 | * // ... | |
347829f5 PP |
119 | * \endcode |
120 | * | |
a40a567e PP |
121 | * Most functions return a status code, one of the values in |
122 | * #bt_object_status. | |
123 | * | |
347829f5 PP |
124 | * You can create a deep copy of any object using the bt_object_copy() |
125 | * function. You can compare two given objects using | |
126 | * bt_object_compare(). | |
127 | * | |
a40a567e PP |
128 | * Any object may be frozen using bt_object_freeze(). You may get the |
129 | * value of a frozen object, but you cannot modify it. Reference | |
130 | * counting still works on frozen objects. You may also copy and compare | |
131 | * frozen objects. | |
132 | * | |
347829f5 PP |
133 | * @author Philippe Proulx <pproulx@efficios.com> |
134 | * @bug No known bugs | |
135 | */ | |
136 | ||
137 | #include <stdint.h> | |
138 | #include <stdbool.h> | |
139 | #include <stddef.h> | |
140 | ||
141 | #ifdef __cplusplus | |
142 | extern "C" { | |
143 | #endif | |
144 | ||
145 | /** | |
146 | * Object type. | |
147 | */ | |
148 | enum bt_object_type { | |
149 | /** Unknown object, used as an error code. */ | |
150 | BT_OBJECT_TYPE_UNKNOWN = -1, | |
151 | ||
152 | /** Null object. */ | |
153 | BT_OBJECT_TYPE_NULL = 0, | |
154 | ||
155 | /** Boolean object (holds \c true or \c false). */ | |
156 | BT_OBJECT_TYPE_BOOL = 1, | |
157 | ||
5584a488 | 158 | /** Integer object (holds a signed 64-bit integer value). */ |
347829f5 PP |
159 | BT_OBJECT_TYPE_INTEGER = 2, |
160 | ||
161 | /** | |
162 | * Floating point number object (holds a \c double value). | |
163 | */ | |
164 | BT_OBJECT_TYPE_FLOAT = 3, | |
165 | ||
166 | /** String object. */ | |
167 | BT_OBJECT_TYPE_STRING = 4, | |
168 | ||
169 | /** Array object. */ | |
170 | BT_OBJECT_TYPE_ARRAY = 5, | |
171 | ||
172 | /** Map object. */ | |
173 | BT_OBJECT_TYPE_MAP = 6, | |
174 | }; | |
175 | ||
4a512e75 | 176 | /** |
a40a567e | 177 | * Status code. |
4a512e75 PP |
178 | */ |
179 | enum bt_object_status { | |
a40a567e PP |
180 | /** Object cannot be altered because it's frozen. */ |
181 | BT_OBJECT_STATUS_FROZEN = -4, | |
182 | ||
4a512e75 | 183 | /** Operation cancelled. */ |
a40a567e PP |
184 | BT_OBJECT_STATUS_CANCELLED = -3, |
185 | ||
186 | /** Invalid arguments. */ | |
187 | /* -22 for compatibility with -EINVAL */ | |
188 | BT_OBJECT_STATUS_INVAL = -22, | |
4a512e75 | 189 | |
a40a567e | 190 | /** General error. */ |
4a512e75 PP |
191 | BT_OBJECT_STATUS_ERROR = -1, |
192 | ||
193 | /** Okay, no error. */ | |
194 | BT_OBJECT_STATUS_OK = 0, | |
195 | }; | |
196 | ||
347829f5 PP |
197 | /** |
198 | * Object. | |
199 | */ | |
200 | struct bt_object; | |
201 | ||
202 | /** | |
203 | * The null object singleton. | |
204 | * | |
e0f99b7f PP |
205 | * Use this everytime you need a null object. |
206 | * | |
207 | * The null object singleton has no reference count; there's only one. | |
208 | * You may directly compare any object to the null object singleton to | |
209 | * find out if it's a null object, or otherwise use bt_object_is_null(). | |
210 | * | |
211 | * The null object singleton is always frozen (see bt_object_freeze() | |
212 | * and bt_object_is_frozen()). | |
347829f5 PP |
213 | * |
214 | * Functions of this API return this when the object is actually a | |
a40a567e PP |
215 | * null object (of type #BT_OBJECT_TYPE_NULL), whereas \c NULL means an |
216 | * error of some sort. | |
347829f5 PP |
217 | */ |
218 | extern struct bt_object *bt_object_null; | |
219 | ||
220 | /** | |
221 | * User function type for bt_object_map_foreach(). | |
222 | * | |
4e2f2908 | 223 | * \p object is a \em weak reference; you must pass it to |
347829f5 PP |
224 | * bt_object_get() to get your own reference. |
225 | * | |
226 | * Return \c true to continue the loop, or \c false to break it. | |
227 | * | |
228 | * @param key Key of map entry | |
229 | * @param object Object of map entry (weak reference) | |
230 | * @param data User data | |
231 | * @returns \c true to continue the loop | |
232 | */ | |
233 | typedef bool (* bt_object_map_foreach_cb)(const char *key, | |
234 | struct bt_object *object, void *data); | |
235 | ||
236 | /** | |
237 | * Puts the object \p _object (calls bt_object_put() on it), and resets | |
238 | * the variable to \c NULL. | |
239 | * | |
240 | * This is something that is often done when putting and object; | |
241 | * resetting the variable to \c NULL makes sure it cannot be put a | |
242 | * second time later. | |
243 | * | |
244 | * @param _object Object to put | |
245 | * | |
246 | * @see BT_OBJECT_MOVE() (moves an object from one variable to the other | |
247 | * without putting it) | |
248 | */ | |
249 | #define BT_OBJECT_PUT(_object) \ | |
250 | do { \ | |
251 | bt_object_put(_object); \ | |
252 | (_object) = NULL; \ | |
253 | } while (0) | |
254 | ||
255 | /** | |
256 | * Moves the object referenced by the variable \p _src_object to the | |
257 | * \p _dst_object variable, then resets \p _src_object to \c NULL. | |
258 | * | |
259 | * The object's reference count is <b>not changed</b>. Resetting | |
260 | * \p _src_object to \c NULL ensures the object will not be put | |
4e2f2908 | 261 | * twice later; its ownership is indeed \em moved from the source |
347829f5 PP |
262 | * variable to the destination variable. |
263 | * | |
264 | * @param _src_object Source object variable | |
265 | * @param _dst_object Destination object variable | |
266 | */ | |
267 | #define BT_OBJECT_MOVE(_dst_object, _src_object) \ | |
268 | do { \ | |
269 | (_dst_object) = (_src_object); \ | |
270 | (_src_object) = NULL; \ | |
271 | } while (0) | |
272 | ||
273 | /** | |
274 | * Increments the reference count of \p object. | |
275 | * | |
276 | * @param object Object of which to increment the reference count | |
7389e8bc PP |
277 | * |
278 | * @see bt_object_put() | |
347829f5 PP |
279 | */ |
280 | extern void bt_object_get(struct bt_object *object); | |
281 | ||
282 | /** | |
283 | * Decrements the reference count of \p object, destroying it when this | |
284 | * count reaches 0. | |
285 | * | |
286 | * @param object Object of which to decrement the reference count | |
287 | * | |
288 | * @see BT_OBJECT_PUT() (puts an object and resets the variable to | |
289 | * \c NULL) | |
7389e8bc | 290 | * @see bt_object_get() |
347829f5 PP |
291 | */ |
292 | extern void bt_object_put(struct bt_object *object); | |
293 | ||
a40a567e PP |
294 | /** |
295 | * Recursively freezes the object \p object. | |
296 | * | |
297 | * A frozen object cannot be modified; it is considered immutable. | |
298 | * Reference counting still works on a frozen object though: you may | |
299 | * pass a frozen object to bt_object_get() and bt_object_put(). | |
300 | * | |
301 | * @param object Object to freeze | |
302 | * @returns One of #bt_object_status values; if \p object | |
303 | * is already frozen, though, #BT_OBJECT_STATUS_OK | |
304 | * is returned anyway (i.e. this function never | |
305 | * returns #BT_OBJECT_STATUS_FROZEN) | |
7389e8bc PP |
306 | * |
307 | * @see bt_object_is_frozen() | |
a40a567e PP |
308 | */ |
309 | extern enum bt_object_status bt_object_freeze(struct bt_object *object); | |
310 | ||
311 | /** | |
312 | * Checks whether \p object is frozen or not. | |
313 | * | |
314 | * @param object Object to check | |
315 | * @returns \c true if \p object is frozen | |
7389e8bc PP |
316 | * |
317 | * @see bt_object_freeze() | |
a40a567e PP |
318 | */ |
319 | extern bool bt_object_is_frozen(const struct bt_object *object); | |
320 | ||
347829f5 PP |
321 | /** |
322 | * Returns the type of \p object. | |
323 | * | |
324 | * @param object Object of which to get the type | |
a40a567e | 325 | * @returns Object's type, or #BT_OBJECT_TYPE_UNKNOWN |
347829f5 PP |
326 | * on error |
327 | * | |
a40a567e | 328 | * @see #bt_object_type (object types) |
7389e8bc PP |
329 | * @see bt_object_is_null() |
330 | * @see bt_object_is_bool() | |
331 | * @see bt_object_is_integer() | |
332 | * @see bt_object_is_float() | |
333 | * @see bt_object_is_string() | |
334 | * @see bt_object_is_array() | |
335 | * @see bt_object_is_map() | |
347829f5 PP |
336 | */ |
337 | extern enum bt_object_type bt_object_get_type(const struct bt_object *object); | |
338 | ||
339 | /** | |
340 | * Checks whether \p object is a null object. The only valid null | |
341 | * object is \ref bt_object_null. | |
342 | * | |
343 | * @param object Object to check | |
344 | * @returns \c true if \p object is a null object | |
7389e8bc PP |
345 | * |
346 | * @see bt_object_get_type() | |
347829f5 | 347 | */ |
eadb143f PP |
348 | static inline |
349 | bool bt_object_is_null(const struct bt_object *object) | |
347829f5 PP |
350 | { |
351 | return bt_object_get_type(object) == BT_OBJECT_TYPE_NULL; | |
352 | } | |
353 | ||
354 | /** | |
355 | * Checks whether \p object is a boolean object. | |
356 | * | |
357 | * @param object Object to check | |
358 | * @returns \c true if \p object is a boolean object | |
7389e8bc PP |
359 | * |
360 | * @see bt_object_get_type() | |
347829f5 | 361 | */ |
eadb143f PP |
362 | static inline |
363 | bool bt_object_is_bool(const struct bt_object *object) | |
347829f5 PP |
364 | { |
365 | return bt_object_get_type(object) == BT_OBJECT_TYPE_BOOL; | |
366 | } | |
367 | ||
368 | /** | |
369 | * Checks whether \p object is an integer object. | |
370 | * | |
371 | * @param object Object to check | |
372 | * @returns \c true if \p object is an integer object | |
7389e8bc PP |
373 | * |
374 | * @see bt_object_get_type() | |
347829f5 | 375 | */ |
eadb143f PP |
376 | static inline |
377 | bool bt_object_is_integer(const struct bt_object *object) | |
347829f5 PP |
378 | { |
379 | return bt_object_get_type(object) == BT_OBJECT_TYPE_INTEGER; | |
380 | } | |
381 | ||
382 | /** | |
383 | * Checks whether \p object is a floating point number object. | |
384 | * | |
385 | * @param object Object to check | |
7389e8bc PP |
386 | * @returns \c true if \p object is a floating point |
387 | * number object | |
388 | * | |
389 | * @see bt_object_get_type() | |
347829f5 | 390 | */ |
eadb143f PP |
391 | static inline |
392 | bool bt_object_is_float(const struct bt_object *object) | |
347829f5 PP |
393 | { |
394 | return bt_object_get_type(object) == BT_OBJECT_TYPE_FLOAT; | |
395 | } | |
396 | ||
397 | /** | |
398 | * Checks whether \p object is a string object. | |
399 | * | |
400 | * @param object Object to check | |
401 | * @returns \c true if \p object is a string object | |
7389e8bc PP |
402 | * |
403 | * @see bt_object_get_type() | |
347829f5 | 404 | */ |
eadb143f PP |
405 | static inline |
406 | bool bt_object_is_string(const struct bt_object *object) | |
347829f5 PP |
407 | { |
408 | return bt_object_get_type(object) == BT_OBJECT_TYPE_STRING; | |
409 | } | |
410 | ||
411 | /** | |
412 | * Checks whether \p object is an array object. | |
413 | * | |
414 | * @param object Object to check | |
415 | * @returns \c true if \p object is an array object | |
7389e8bc PP |
416 | * |
417 | * @see bt_object_get_type() | |
347829f5 | 418 | */ |
eadb143f PP |
419 | static inline |
420 | bool bt_object_is_array(const struct bt_object *object) | |
347829f5 PP |
421 | { |
422 | return bt_object_get_type(object) == BT_OBJECT_TYPE_ARRAY; | |
423 | } | |
424 | ||
425 | /** | |
426 | * Checks whether \p object is a map object. | |
427 | * | |
428 | * @param object Object to check | |
429 | * @returns \c true if \p object is a map object | |
7389e8bc PP |
430 | * |
431 | * @see bt_object_get_type() | |
347829f5 | 432 | */ |
eadb143f PP |
433 | static inline |
434 | bool bt_object_is_map(const struct bt_object *object) | |
347829f5 PP |
435 | { |
436 | return bt_object_get_type(object) == BT_OBJECT_TYPE_MAP; | |
437 | } | |
438 | ||
439 | /** | |
440 | * Creates a boolean object. The created boolean object's initial value | |
441 | * is \c false. | |
442 | * | |
443 | * The created object's reference count is set to 1. | |
444 | * | |
445 | * @returns Created object on success, or \c NULL on error | |
7389e8bc PP |
446 | * |
447 | * @see bt_object_bool_create_init() (creates an initialized | |
448 | * boolean object) | |
347829f5 PP |
449 | */ |
450 | extern struct bt_object *bt_object_bool_create(void); | |
451 | ||
452 | /** | |
453 | * Creates a boolean object with its initial value set to \p val. | |
454 | * | |
455 | * The created object's reference count is set to 1. | |
456 | * | |
457 | * @param val Initial value | |
458 | * @returns Created object on success, or \c NULL on error | |
459 | */ | |
460 | extern struct bt_object *bt_object_bool_create_init(bool val); | |
461 | ||
462 | /** | |
463 | * Creates an integer object. The created integer object's initial value | |
464 | * is 0. | |
465 | * | |
466 | * The created object's reference count is set to 1. | |
467 | * | |
468 | * @returns Created object on success, or \c NULL on error | |
7389e8bc PP |
469 | * |
470 | * @see bt_object_integer_create_init() (creates an initialized | |
471 | * integer object) | |
347829f5 PP |
472 | */ |
473 | extern struct bt_object *bt_object_integer_create(void); | |
474 | ||
475 | /** | |
476 | * Creates an integer object with its initial value set to \p val. | |
477 | * | |
478 | * The created object's reference count is set to 1. | |
479 | * | |
480 | * @param val Initial value | |
481 | * @returns Created object on success, or \c NULL on error | |
482 | */ | |
483 | extern struct bt_object *bt_object_integer_create_init(int64_t val); | |
484 | ||
485 | /** | |
486 | * Creates a floating point number object. The created floating point | |
487 | * number object's initial value is 0. | |
488 | * | |
489 | * The created object's reference count is set to 1. | |
490 | * | |
491 | * @returns Created object on success, or \c NULL on error | |
7389e8bc PP |
492 | * |
493 | * @see bt_object_float_create_init() (creates an initialized floating | |
494 | * point number object) | |
347829f5 PP |
495 | */ |
496 | extern struct bt_object *bt_object_float_create(void); | |
497 | ||
498 | /** | |
499 | * Creates a floating point number object with its initial value set | |
500 | * to \p val. | |
501 | * | |
502 | * The created object's reference count is set to 1. | |
503 | * | |
504 | * @param val Initial value | |
505 | * @returns Created object on success, or \c NULL on error | |
506 | */ | |
507 | extern struct bt_object *bt_object_float_create_init(double val); | |
508 | ||
509 | /** | |
510 | * Creates a string object. The string object is initially empty. | |
511 | * | |
512 | * The created object's reference count is set to 1. | |
513 | * | |
514 | * @returns Created object on success, or \c NULL on error | |
7389e8bc PP |
515 | * |
516 | * @see bt_object_string_create_init() (creates an initialized | |
517 | * string object) | |
347829f5 PP |
518 | */ |
519 | extern struct bt_object *bt_object_string_create(void); | |
520 | ||
521 | /** | |
522 | * Creates a string object with its initial value set to \p val. | |
523 | * | |
524 | * \p val is copied. | |
525 | * | |
526 | * The created object's reference count is set to 1. | |
527 | * | |
528 | * @param val Initial value (will be copied) | |
529 | * @returns Created object on success, or \c NULL on error | |
530 | */ | |
531 | extern struct bt_object *bt_object_string_create_init(const char *val); | |
532 | ||
533 | /** | |
534 | * Creates an empty array object. | |
535 | * | |
536 | * The created object's reference count is set to 1. | |
537 | * | |
538 | * @returns Created object on success, or \c NULL on error | |
539 | */ | |
540 | extern struct bt_object *bt_object_array_create(void); | |
541 | ||
542 | /** | |
543 | * Creates an empty map object. | |
544 | * | |
545 | * The created object's reference count is set to 1. | |
546 | * | |
547 | * @returns Created object on success, or \c NULL on error | |
548 | */ | |
549 | extern struct bt_object *bt_object_map_create(void); | |
550 | ||
551 | /** | |
a40a567e | 552 | * Gets the boolean value of the boolean object \p bool_obj. |
347829f5 PP |
553 | * |
554 | * @param bool_obj Boolean object | |
555 | * @param val Returned boolean value | |
a40a567e | 556 | * @returns One of #bt_object_status values |
7389e8bc PP |
557 | * |
558 | * @see bt_object_bool_set() | |
347829f5 | 559 | */ |
a40a567e PP |
560 | extern enum bt_object_status bt_object_bool_get( |
561 | const struct bt_object *bool_obj, bool *val); | |
347829f5 PP |
562 | |
563 | /** | |
564 | * Sets the boolean value of the boolean object \p bool_obj to \p val. | |
565 | * | |
566 | * @param bool_obj Boolean object | |
567 | * @param val New boolean value | |
a40a567e | 568 | * @returns One of #bt_object_status values |
7389e8bc PP |
569 | * |
570 | * @see bt_object_bool_get() | |
347829f5 | 571 | */ |
a40a567e PP |
572 | extern enum bt_object_status bt_object_bool_set(struct bt_object *bool_obj, |
573 | bool val); | |
347829f5 PP |
574 | |
575 | /** | |
a40a567e | 576 | * Gets the integer value of the integer object \p integer_obj. |
347829f5 PP |
577 | * |
578 | * @param integer_obj Integer object | |
579 | * @param val Returned integer value | |
a40a567e | 580 | * @returns One of #bt_object_status values |
7389e8bc PP |
581 | * |
582 | * @see bt_object_integer_set() | |
347829f5 | 583 | */ |
a40a567e PP |
584 | extern enum bt_object_status bt_object_integer_get( |
585 | const struct bt_object *integer_obj, int64_t *val); | |
347829f5 PP |
586 | |
587 | /** | |
588 | * Sets the integer value of the integer object \p integer_obj to | |
589 | * \p val. | |
590 | * | |
591 | * @param integer_obj Integer object | |
592 | * @param val New integer value | |
a40a567e | 593 | * @returns One of #bt_object_status values |
7389e8bc PP |
594 | * |
595 | * @see bt_object_integer_get() | |
347829f5 | 596 | */ |
a40a567e PP |
597 | extern enum bt_object_status bt_object_integer_set( |
598 | struct bt_object *integer_obj, int64_t val); | |
347829f5 PP |
599 | |
600 | /** | |
601 | * Gets the floating point number value of the floating point number | |
a40a567e | 602 | * object \p float_obj. |
347829f5 PP |
603 | * |
604 | * @param float_obj Floating point number object | |
605 | * @param val Returned floating point number value | |
a40a567e | 606 | * @returns One of #bt_object_status values |
7389e8bc PP |
607 | * |
608 | * @see bt_object_float_set() | |
347829f5 | 609 | */ |
a40a567e PP |
610 | extern enum bt_object_status bt_object_float_get( |
611 | const struct bt_object *float_obj, double *val); | |
347829f5 PP |
612 | |
613 | /** | |
614 | * Sets the floating point number value of the floating point number | |
615 | * object \p float_obj to \p val. | |
616 | * | |
617 | * @param float_obj Floating point number object | |
618 | * @param val New floating point number value | |
a40a567e | 619 | * @returns One of #bt_object_status values |
7389e8bc PP |
620 | * |
621 | * @see bt_object_float_get() | |
347829f5 | 622 | */ |
a40a567e PP |
623 | extern enum bt_object_status bt_object_float_set( |
624 | struct bt_object *float_obj, double val); | |
347829f5 PP |
625 | |
626 | /** | |
a40a567e | 627 | * Gets the string value of the string object \p string_obj. The |
347829f5 | 628 | * returned string is valid as long as this object exists and is not |
a40a567e PP |
629 | * modified. The ownership of the returned string is \em not |
630 | * transferred to the caller. | |
347829f5 PP |
631 | * |
632 | * @param string_obj String object | |
a40a567e PP |
633 | * @param val Returned string value |
634 | * @returns One of #bt_object_status values | |
7389e8bc PP |
635 | * |
636 | * @see bt_object_string_set() | |
347829f5 | 637 | */ |
a40a567e PP |
638 | extern enum bt_object_status bt_object_string_get( |
639 | const struct bt_object *string_obj, const char **val); | |
347829f5 PP |
640 | |
641 | /** | |
642 | * Sets the string value of the string object \p string_obj to | |
643 | * \p val. | |
644 | * | |
645 | * \p val is copied. | |
646 | * | |
647 | * @param string_obj String object | |
648 | * @param val New string value (copied) | |
a40a567e | 649 | * @returns One of #bt_object_status values |
7389e8bc PP |
650 | * |
651 | * @see bt_object_string_get() | |
347829f5 | 652 | */ |
a40a567e PP |
653 | extern enum bt_object_status bt_object_string_set(struct bt_object *string_obj, |
654 | const char *val); | |
347829f5 PP |
655 | |
656 | /** | |
657 | * Gets the size of the array object \p array_obj, that is, the number | |
658 | * of elements contained in \p array_obj. | |
659 | * | |
660 | * @param array_obj Array object | |
a40a567e PP |
661 | * @returns Array size if the return value is 0 (empty) or a |
662 | * positive value, or one of | |
663 | * #bt_object_status negative values otherwise | |
7389e8bc PP |
664 | * |
665 | * @see bt_object_array_is_empty() | |
347829f5 PP |
666 | */ |
667 | extern int bt_object_array_size(const struct bt_object *array_obj); | |
668 | ||
669 | /** | |
670 | * Returns \c true if the array object \p array_obj. | |
671 | * | |
672 | * @param array_obj Array object | |
673 | * @returns \c true if \p array_obj is empty | |
7389e8bc PP |
674 | * |
675 | * @see bt_object_array_size() | |
347829f5 PP |
676 | */ |
677 | extern bool bt_object_array_is_empty(const struct bt_object *array_obj); | |
678 | ||
679 | /** | |
680 | * Gets the element object of the array object \p array_obj at the | |
681 | * index \p index. | |
682 | * | |
683 | * The returned object's reference count is incremented, unless it's | |
684 | * a null object. | |
685 | * | |
686 | * @param array_obj Array object | |
687 | * @param index Index of element to get | |
688 | * @returns Element object at index \p index on success, | |
689 | * or \c NULL on error | |
690 | */ | |
691 | extern struct bt_object *bt_object_array_get(const struct bt_object *array_obj, | |
692 | size_t index); | |
693 | ||
694 | /** | |
695 | * Appends the element object \p element_obj to the array object | |
696 | * \p array_obj. | |
697 | * | |
698 | * The appended object's reference count is incremented, unless it's | |
699 | * a null object. | |
700 | * | |
701 | * @param array_obj Array object | |
702 | * @param element_obj Element object to append | |
a40a567e | 703 | * @returns One of #bt_object_status values |
7389e8bc PP |
704 | * |
705 | * @see bt_object_array_append_bool() | |
706 | * @see bt_object_array_append_integer() | |
707 | * @see bt_object_array_append_float() | |
708 | * @see bt_object_array_append_string() | |
709 | * @see bt_object_array_append_array() | |
710 | * @see bt_object_array_append_map() | |
347829f5 | 711 | */ |
a40a567e | 712 | extern enum bt_object_status bt_object_array_append(struct bt_object *array_obj, |
347829f5 PP |
713 | struct bt_object *element_obj); |
714 | ||
715 | /** | |
716 | * Appends the boolean value \p val to the array object \p array_obj. | |
717 | * This is a convenience function which creates the underlying boolean | |
718 | * object before appending it. | |
719 | * | |
720 | * The created boolean object's reference count is set to 1. | |
721 | * | |
722 | * @param array_obj Array object | |
723 | * @param val Boolean value to append | |
a40a567e | 724 | * @returns One of #bt_object_status values |
7389e8bc PP |
725 | * |
726 | * @see bt_object_array_append() | |
347829f5 | 727 | */ |
a40a567e PP |
728 | extern enum bt_object_status bt_object_array_append_bool( |
729 | struct bt_object *array_obj, bool val); | |
347829f5 PP |
730 | |
731 | /** | |
732 | * Appends the integer value \p val to the array object \p array_obj. | |
733 | * This is a convenience function which creates the underlying integer | |
734 | * object before appending it. | |
735 | * | |
736 | * The created integer object's reference count is set to 1. | |
737 | * | |
738 | * @param array_obj Array object | |
739 | * @param val Integer value to append | |
a40a567e | 740 | * @returns One of #bt_object_status values |
7389e8bc PP |
741 | * |
742 | * @see bt_object_array_append() | |
347829f5 | 743 | */ |
a40a567e PP |
744 | extern enum bt_object_status bt_object_array_append_integer( |
745 | struct bt_object *array_obj, int64_t val); | |
347829f5 PP |
746 | |
747 | /** | |
748 | * Appends the floating point number value \p val to the array object | |
749 | * \p array_obj. This is a convenience function which creates the | |
750 | * underlying floating point number object before appending it. | |
751 | * | |
752 | * The created floating point number object's reference count is | |
753 | * set to 1. | |
754 | * | |
755 | * @param array_obj Array object | |
756 | * @param val Floating point number value to append | |
a40a567e | 757 | * @returns One of #bt_object_status values |
7389e8bc PP |
758 | * |
759 | * @see bt_object_array_append() | |
347829f5 | 760 | */ |
a40a567e PP |
761 | extern enum bt_object_status bt_object_array_append_float( |
762 | struct bt_object *array_obj, double val); | |
347829f5 PP |
763 | |
764 | /** | |
765 | * Appends the string value \p val to the array object \p array_obj. | |
766 | * This is a convenience function which creates the underlying string | |
767 | * object before appending it. | |
768 | * | |
769 | * \p val is copied. | |
770 | * | |
771 | * The created string object's reference count is set to 1. | |
772 | * | |
773 | * @param array_obj Array object | |
774 | * @param val String value to append (copied) | |
a40a567e | 775 | * @returns One of #bt_object_status values |
7389e8bc PP |
776 | * |
777 | * @see bt_object_array_append() | |
347829f5 | 778 | */ |
a40a567e PP |
779 | extern enum bt_object_status bt_object_array_append_string( |
780 | struct bt_object *array_obj, const char *val); | |
347829f5 PP |
781 | |
782 | /** | |
783 | * Appends an empty array object to the array object \p array_obj. | |
784 | * This is a convenience function which creates the underlying array | |
785 | * object before appending it. | |
786 | * | |
787 | * The created array object's reference count is set to 1. | |
788 | * | |
789 | * @param array_obj Array object | |
a40a567e | 790 | * @returns One of #bt_object_status values |
7389e8bc PP |
791 | * |
792 | * @see bt_object_array_append() | |
347829f5 | 793 | */ |
a40a567e PP |
794 | extern enum bt_object_status bt_object_array_append_array( |
795 | struct bt_object *array_obj); | |
347829f5 PP |
796 | |
797 | /** | |
798 | * Appends an empty map object to the array object \p array_obj. This | |
799 | * is a convenience function which creates the underlying map object | |
800 | * before appending it. | |
801 | * | |
802 | * The created map object's reference count is set to 1. | |
803 | * | |
804 | * @param array_obj Array object | |
a40a567e | 805 | * @returns One of #bt_object_status values |
7389e8bc PP |
806 | * |
807 | * @see bt_object_array_append() | |
347829f5 | 808 | */ |
a40a567e PP |
809 | extern enum bt_object_status bt_object_array_append_map( |
810 | struct bt_object *array_obj); | |
347829f5 | 811 | |
3695540c PP |
812 | /** |
813 | * Replaces the element object at index \p index of the array object | |
814 | * \p array_obj by \p element_obj. | |
815 | * | |
816 | * The replaced object's reference count is decremented, unless it's | |
817 | * a null object. The reference count of \p element_obj is incremented, | |
818 | * unless it's a null object. | |
819 | * | |
820 | * @param array_obj Array object | |
821 | * @param index Index of element object to replace | |
822 | * @param element_obj New element object at position \p index of | |
823 | * \p array_obj | |
a40a567e | 824 | * @returns One of #bt_object_status values |
3695540c | 825 | */ |
a40a567e PP |
826 | extern enum bt_object_status bt_object_array_set(struct bt_object *array_obj, |
827 | size_t index, struct bt_object *element_obj); | |
3695540c | 828 | |
347829f5 PP |
829 | /** |
830 | * Gets the size of a map object, that is, the number of elements | |
831 | * contained in a map object. | |
832 | * | |
833 | * @param map_obj Map object | |
a40a567e PP |
834 | * @returns Map size if the return value is 0 (empty) or a |
835 | * positive value, or one of | |
836 | * #bt_object_status negative values otherwise | |
7389e8bc PP |
837 | * |
838 | * @see bt_object_map_is_empty() | |
347829f5 PP |
839 | */ |
840 | extern int bt_object_map_size(const struct bt_object *map_obj); | |
841 | ||
842 | /** | |
843 | * Returns \c true if the map object \p map_obj. | |
844 | * | |
845 | * @param map_obj Map object | |
846 | * @returns \c true if \p map_obj is empty | |
7389e8bc PP |
847 | * |
848 | * @see bt_object_map_size() | |
347829f5 PP |
849 | */ |
850 | extern bool bt_object_map_is_empty(const struct bt_object *map_obj); | |
851 | ||
852 | /** | |
853 | * Gets the element object associated with the key \p key within the | |
854 | * map object \p map_obj. | |
855 | * | |
856 | * The returned object's reference count is incremented, unless it's | |
857 | * a null object. | |
858 | * | |
859 | * @param map_obj Map object | |
860 | * @param key Key of the element to get | |
861 | * @returns Element object associated with the key \p key | |
862 | * on success, or \c NULL on error | |
863 | */ | |
864 | extern struct bt_object *bt_object_map_get(const struct bt_object *map_obj, | |
865 | const char *key); | |
866 | ||
867 | /** | |
868 | * Calls a provided user function \p cb for each element of the map | |
869 | * object \p map_obj. | |
870 | * | |
871 | * The object passed to the user function is a <b>weak reference</b>: | |
872 | * you must call bt_object_get() on it to obtain your own reference. | |
873 | * | |
874 | * The key passed to the user function is only valid in the scope of | |
875 | * this user function. | |
876 | * | |
877 | * The user function must return \c true to continue the loop, or | |
878 | * \c false to break it. | |
879 | * | |
880 | * @param map_obj Map object | |
881 | * @param cb User function to call back | |
882 | * @param data User data passed to the user function | |
a40a567e PP |
883 | * @returns One of #bt_object_status values; more |
884 | * specifically, #BT_OBJECT_STATUS_CANCELLED is | |
885 | * returned if the loop was cancelled by the user | |
886 | * function | |
4a512e75 PP |
887 | */ |
888 | extern enum bt_object_status bt_object_map_foreach( | |
889 | const struct bt_object *map_obj, bt_object_map_foreach_cb cb, | |
890 | void *data); | |
347829f5 PP |
891 | |
892 | /** | |
893 | * Returns whether or not the map object \p map_obj contains the | |
894 | * key \p key. | |
895 | * | |
896 | * @param map_obj Map object | |
897 | * @param key Key to check | |
898 | * @returns \c true if \p map_obj contains the key \p key, | |
899 | * or \c false if it doesn't have \p key or | |
900 | * on error | |
901 | */ | |
902 | extern bool bt_object_map_has_key(const struct bt_object *map_obj, | |
903 | const char *key); | |
904 | ||
905 | /** | |
906 | * Inserts the element object \p element_obj associated with the key | |
907 | * \p key into the map object \p map_obj. If \p key exists in | |
908 | * \p map_obj, the associated element object is first put, and then | |
909 | * replaced by \p element_obj. | |
910 | * | |
911 | * \p key is copied. | |
912 | * | |
913 | * The inserted object's reference count is incremented, unless it's | |
914 | * a null object. | |
915 | * | |
916 | * @param map_obj Map object | |
917 | * @param key Key (copied) of object to insert | |
918 | * @param element_obj Element object to insert, associated with the | |
919 | * key \p key | |
a40a567e | 920 | * @returns One of #bt_object_status values |
7389e8bc PP |
921 | * |
922 | * @see bt_object_map_insert_bool() | |
923 | * @see bt_object_map_insert_integer() | |
924 | * @see bt_object_map_insert_float() | |
925 | * @see bt_object_map_insert_string() | |
926 | * @see bt_object_map_insert_array() | |
927 | * @see bt_object_map_insert_map() | |
347829f5 | 928 | */ |
a40a567e PP |
929 | extern enum bt_object_status bt_object_map_insert( |
930 | struct bt_object *map_obj, const char *key, | |
931 | struct bt_object *element_obj); | |
347829f5 PP |
932 | |
933 | /** | |
934 | * Inserts the boolean value \p val associated with the key \p key into | |
935 | * the map object \p map_obj. This is a convenience function which | |
936 | * creates the underlying boolean object before inserting it. | |
937 | * | |
938 | * \p key is copied. | |
939 | * | |
940 | * The created boolean object's reference count is set to 1. | |
941 | * | |
942 | * @param map_obj Map object | |
943 | * @param key Key (copied) of boolean value to insert | |
944 | * @param val Boolean value to insert, associated with the | |
945 | * key \p key | |
a40a567e | 946 | * @returns One of #bt_object_status values |
7389e8bc PP |
947 | * |
948 | * @see bt_object_map_insert() | |
347829f5 | 949 | */ |
a40a567e PP |
950 | extern enum bt_object_status bt_object_map_insert_bool( |
951 | struct bt_object *map_obj, const char *key, bool val); | |
347829f5 PP |
952 | |
953 | /** | |
954 | * Inserts the integer value \p val associated with the key \p key into | |
955 | * the map object \p map_obj. This is a convenience function which | |
956 | * creates the underlying integer object before inserting it. | |
957 | * | |
958 | * \p key is copied. | |
959 | * | |
960 | * The created integer object's reference count is set to 1. | |
961 | * | |
962 | * @param map_obj Map object | |
963 | * @param key Key (copied) of integer value to insert | |
964 | * @param val Integer value to insert, associated with the | |
965 | * key \p key | |
a40a567e | 966 | * @returns One of #bt_object_status values |
7389e8bc PP |
967 | * |
968 | * @see bt_object_map_insert() | |
347829f5 | 969 | */ |
a40a567e PP |
970 | extern enum bt_object_status bt_object_map_insert_integer( |
971 | struct bt_object *map_obj, const char *key, int64_t val); | |
347829f5 PP |
972 | |
973 | /** | |
974 | * Inserts the floating point number value \p val associated with the | |
975 | * key \p key into the map object \p map_obj. This is a convenience | |
976 | * function which creates the underlying floating point number object | |
977 | * before inserting it. | |
978 | * | |
979 | * \p key is copied. | |
980 | * | |
981 | * The created floating point number object's reference count is | |
982 | * set to 1. | |
983 | * | |
984 | * @param map_obj Map object | |
985 | * @param key Key (copied) of floating point number value to | |
986 | * insert | |
987 | * @param val Floating point number value to insert, | |
988 | * associated with the key \p key | |
a40a567e | 989 | * @returns One of #bt_object_status values |
7389e8bc PP |
990 | * |
991 | * @see bt_object_map_insert() | |
347829f5 | 992 | */ |
a40a567e PP |
993 | extern enum bt_object_status bt_object_map_insert_float( |
994 | struct bt_object *map_obj, const char *key, double val); | |
347829f5 PP |
995 | |
996 | /** | |
997 | * Inserts the string value \p val associated with the key \p key into | |
998 | * the map object \p map_obj. This is a convenience function which | |
999 | * creates the underlying string object before inserting it. | |
1000 | * | |
1001 | * \p val and \p key are copied. | |
1002 | * | |
1003 | * The created string object's reference count is set to 1. | |
1004 | * | |
1005 | * @param map_obj Map object | |
1006 | * @param key Key (copied) of string value to insert | |
1007 | * @param val String value to insert, associated with the | |
1008 | * key \p key | |
a40a567e | 1009 | * @returns One of #bt_object_status values |
7389e8bc PP |
1010 | * |
1011 | * @see bt_object_map_insert() | |
347829f5 | 1012 | */ |
a40a567e PP |
1013 | extern enum bt_object_status bt_object_map_insert_string( |
1014 | struct bt_object *map_obj, const char *key, const char *val); | |
347829f5 PP |
1015 | |
1016 | /** | |
1017 | * Inserts an empty array object associated with the key \p key into | |
1018 | * the map object \p map_obj. This is a convenience function which | |
1019 | * creates the underlying array object before inserting it. | |
1020 | * | |
1021 | * \p key is copied. | |
1022 | * | |
1023 | * The created array object's reference count is set to 1. | |
1024 | * | |
1025 | * @param map_obj Map object | |
1026 | * @param key Key (copied) of empty array to insert | |
a40a567e | 1027 | * @returns One of #bt_object_status values |
7389e8bc PP |
1028 | * |
1029 | * @see bt_object_map_insert() | |
347829f5 | 1030 | */ |
a40a567e PP |
1031 | extern enum bt_object_status bt_object_map_insert_array( |
1032 | struct bt_object *map_obj, const char *key); | |
347829f5 PP |
1033 | |
1034 | /** | |
1035 | * Inserts an empty map object associated with the key \p key into | |
1036 | * the map object \p map_obj. This is a convenience function which | |
1037 | * creates the underlying map object before inserting it. | |
1038 | * | |
1039 | * \p key is copied. | |
1040 | * | |
1041 | * The created map object's reference count is set to 1. | |
1042 | * | |
1043 | * @param map_obj Map object | |
1044 | * @param key Key (copied) of empty map to insert | |
a40a567e | 1045 | * @returns One of #bt_object_status values |
7389e8bc PP |
1046 | * |
1047 | * @see bt_object_map_insert() | |
347829f5 | 1048 | */ |
a40a567e PP |
1049 | extern enum bt_object_status bt_object_map_insert_map( |
1050 | struct bt_object *map_obj, const char *key); | |
347829f5 PP |
1051 | |
1052 | /** | |
1053 | * Creates a deep copy of the object \p object. | |
1054 | * | |
1055 | * The created object's reference count is set to 1, unless | |
1056 | * \p object is a null object. | |
1057 | * | |
1058 | * @param object Object to copy | |
1059 | * @returns Deep copy of \p object on success, or \c NULL | |
1060 | * on error | |
1061 | */ | |
1062 | extern struct bt_object *bt_object_copy(const struct bt_object *object); | |
1063 | ||
1064 | /** | |
1065 | * Compares the objects \p object_a and \p object_b and returns \c true | |
1066 | * if they have the same content. | |
1067 | * | |
1068 | * @param object_a Object A | |
7389e8bc | 1069 | * @param object_b Object B |
347829f5 PP |
1070 | * @returns \c true if \p object_a and \p object_b have the |
1071 | * same content, or \c false if they differ or on | |
1072 | * error | |
1073 | */ | |
1074 | extern bool bt_object_compare(const struct bt_object *object_a, | |
1075 | const struct bt_object *object_b); | |
1076 | ||
1077 | #ifdef __cplusplus | |
1078 | } | |
1079 | #endif | |
1080 | ||
1081 | #endif /* _BABELTRACE_OBJECTS_H */ |