common: uuid: add `uuid_to_str` which returns an std::string
[lttng-tools.git] / src / common / optional.hpp
CommitLineData
2c5ff4e4 1/*
ab5be9fa 2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
2c5ff4e4 3 *
ab5be9fa 4 * SPDX-License-Identifier: GPL-2.0-only
2c5ff4e4 5 *
2c5ff4e4
JG
6 */
7
8#ifndef LTTNG_OPTIONAL_H
9#define LTTNG_OPTIONAL_H
10
11#include <stdint.h>
2c5ff4e4
JG
12
13/*
14 * Define wrapper structure representing an optional value.
15 *
16 * This macro defines an "is_set" boolean field that must be checked
17 * when accessing the optional field. This "is_set" field provides
18 * the semantics that would be expected of a typical "raw pointer" field
19 * which would be checked for NULL.
20 *
21 * Prefer using this macro where "special" values would be used, e.g.
22 * -1ULL for uint64_t types.
23 *
2c5ff4e4
JG
24 * Declaration example:
25 * struct my_struct {
26 * int a;
8250d597 27 * LTTNG_OPTIONAL(int) b;
2c5ff4e4
JG
28 * };
29 *
30 * Usage example:
31 * struct my_struct foo = LTTNG_OPTIONAL_INIT;
32 *
33 * LTTNG_OPTIONAL_SET(&foo.b, 42);
34 * if (foo.b.is_set) {
35 * printf("%d", foo.b.value);
36 * }
37 *
38 * LTTNG_OPTIONAL_UNSET(&foo.b);
39 */
40#define LTTNG_OPTIONAL(type) \
41 struct { \
42 uint8_t is_set; \
43 type value; \
44 }
45
0a30bf9b
JG
46/*
47 * Alias used for communication structures. If the layout of an LTTNG_OPTIONAL
48 * is changed, the original layout should still be used for communication
49 * purposes.
50 *
51 * LTTNG_OPTIONAL_COMM should be combined with the LTTNG_PACKED macro when
52 * used for IPC / network communication.
53 */
54#define LTTNG_OPTIONAL_COMM LTTNG_OPTIONAL
55
2c5ff4e4
JG
56/*
57 * This macro is available as a 'convenience' to allow sites that assume
a0377dfe 58 * an optional value is set to LTTNG_ASSERT() that it is set when accessing it.
2c5ff4e4
JG
59 *
60 * Since this returns the 'optional' by value, it is not suitable for all
61 * wrapped optional types. It is meant to be used with PODs.
62 */
63#define LTTNG_OPTIONAL_GET(optional) \
a321667a 64 ({ \
a0377dfe 65 LTTNG_ASSERT((optional).is_set); \
bc2dc8d4 66 (optional).value; \
2c5ff4e4
JG
67 })
68
3da864a9
JR
69/*
70 * This macro is available as a 'convenience' to allow sites that assume
a0377dfe 71 * an optional value is set to LTTNG_ASSERT() that it is set when fecthing the
3da864a9
JR
72 * underlying value's address.
73 */
74#define LTTNG_OPTIONAL_GET_PTR(optional) \
75 ({ \
a0377dfe 76 LTTNG_ASSERT((optional).is_set); \
3da864a9
JR
77 &(optional).value; \
78 })
79
2c5ff4e4 80/*
5747e45a 81 * Initialize an optional field as unset.
2c5ff4e4
JG
82 *
83 * The wrapped field is set to the value it would gave if it had static storage
84 * duration.
85 */
1c9a0b0e 86#define LTTNG_OPTIONAL_INIT_UNSET {}
5747e45a
JG
87
88/*
89 * Initialize an optional field as 'set' with a given value.
90 */
7966af57 91#define LTTNG_OPTIONAL_INIT_VALUE(val) { .is_set = 1, .value = val }
2c5ff4e4
JG
92
93/* Set the value of an optional field. */
bc2dc8d4
MD
94#define LTTNG_OPTIONAL_SET(field_ptr, val) \
95 do { \
bc2dc8d4 96 (field_ptr)->is_set = 1; \
7966af57 97 (field_ptr)->value = (val); \
bc2dc8d4 98 } while (0)
2c5ff4e4
JG
99
100/* Put an optional field in the "unset" (NULL-ed) state. */
bc2dc8d4
MD
101#define LTTNG_OPTIONAL_UNSET(field_ptr) \
102 do { \
103 (field_ptr)->is_set = 0; \
104 } while (0)
2c5ff4e4
JG
105
106#endif /* LTTNG_OPTIONAL_H */
This page took 0.053576 seconds and 4 git commands to generate.