Commit | Line | Data |
---|---|---|
c0a66c84 JG |
1 | /* |
2 | * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
3 | * | |
4 | * SPDX-License-Identifier: LGPL-2.1-only | |
5 | * | |
6 | */ | |
7 | ||
8 | #ifndef LTTNG_PAYLOAD_VIEW_H | |
9 | #define LTTNG_PAYLOAD_VIEW_H | |
10 | ||
11 | #include <common/buffer-view.h> | |
12 | #include <common/dynamic-array.h> | |
13 | ||
7966af57 SM |
14 | #ifdef __cplusplus |
15 | extern "C" { | |
16 | #endif | |
17 | ||
c0a66c84 | 18 | struct lttng_payload; |
fe489250 | 19 | struct fd_handle; |
c0a66c84 JG |
20 | |
21 | /* | |
22 | * An lttng_payload_view references a payload and allows code to share | |
23 | * a `const` version of a subset of a payload. | |
24 | * | |
25 | * A payload view is invalidated whenever its source (a payload, or another | |
26 | * payload view) is modified. | |
27 | * | |
28 | * While a payload view does not allow users to modify the underlying bytes | |
fe489250 JG |
29 | * of the payload, it can be used to 'pop' file descriptor handles using an |
30 | * iterator belonging to the top-level payload view. | |
c0a66c84 JG |
31 | * |
32 | * Hence, a payload view created from a payload or a dynamic buffer contains | |
fe489250 JG |
33 | * an implicit file descriptor handle iterator. Any payload view created from |
34 | * another payload view will share the same underlying file descriptor handle | |
35 | * iterator. | |
c0a66c84 | 36 | * |
fe489250 JG |
37 | * The rationale for this is that a payload is never consumed directly, it must |
38 | * be consumed through a payload view. | |
c0a66c84 JG |
39 | * |
40 | * Typically, a payload view will be used to rebuild a previously serialized | |
41 | * object hierarchy. Sharing an underlying iterator allows aggregate objects | |
42 | * to provide a restricted view of the payload to their members, which will | |
fe489250 | 43 | * report the number of bytes consumed and `pop` the file descriptor handle they |
c0a66c84 | 44 | * should own. In return, those objects can create an even narrower view for |
fe489250 | 45 | * their children, allowing them to also consume file descriptor handles. |
c0a66c84 JG |
46 | * |
47 | * Note that a payload view never assumes any ownership of the underlying | |
48 | * payload. | |
49 | */ | |
50 | struct lttng_payload_view { | |
51 | struct lttng_buffer_view buffer; | |
52 | /* private */ | |
7966af57 SM |
53 | |
54 | /* | |
55 | * Avoid a -Wreturn-type-c-linkage warning with clang. | |
56 | * gcc is more permissive with regards to this warning, but | |
57 | * clang is right that a structure containing a _const_ structure is not | |
58 | * a trivial type in the eyes of the C++ standard, theoritically affecting its | |
59 | * compatibility with C from an ABI standpoint: | |
60 | * A trivial class is a class that is trivially copyable and has one or | |
61 | * more default constructors, all of which are either trivial or deleted and | |
62 | * at least one of which is not deleted. | |
63 | * | |
64 | * A const member implicitly deletes lttng_payload_view's constructor, | |
65 | * making it non-trivial. This is not a problem for the moment as we are | |
66 | * transitioning all code to C++11. | |
67 | */ | |
68 | #if !defined(__cplusplus) | |
69 | const | |
70 | #endif | |
71 | struct lttng_dynamic_pointer_array _fd_handles; | |
72 | ||
c0a66c84 | 73 | struct { |
fe489250 JG |
74 | size_t *p_fd_handles_position; |
75 | size_t fd_handles_position; | |
c0a66c84 JG |
76 | } _iterator; |
77 | }; | |
78 | ||
3e6e0df2 JG |
79 | /** |
80 | * Checks if a payload view's buffer is safe to access. | |
81 | * | |
82 | * After calling the payload view creation functions, callers should verify | |
83 | * if the resquested length (if any is explicitly provided) could be mapped | |
84 | * to a new view. | |
b2530e4d JG |
85 | * |
86 | * @view Payload to validate | |
3e6e0df2 | 87 | */ |
3e6e0df2 JG |
88 | bool lttng_payload_view_is_valid(const struct lttng_payload_view *view); |
89 | ||
c0a66c84 JG |
90 | /** |
91 | * Return a payload view referencing a subset of a payload. | |
92 | * | |
93 | * @payload Source payload to reference | |
94 | * @offset Offset to apply to the payload's buffer | |
95 | * @len Length of the contents to reference. Passing -1 will | |
96 | * cause the view to reference the whole payload from the | |
97 | * offset provided. | |
98 | */ | |
c0a66c84 JG |
99 | struct lttng_payload_view lttng_payload_view_from_payload( |
100 | const struct lttng_payload *payload, size_t offset, | |
101 | ptrdiff_t len); | |
102 | ||
103 | /** | |
104 | * Return a payload view referencing a subset of a payload referenced by | |
105 | * another payload view. | |
106 | * | |
107 | * @view Source payload view to reference | |
108 | * @offset Offset to apply to the payload view's buffer view | |
109 | * @len Length of the contents to reference. Passing -1 will | |
110 | * cause the payload view to reference the whole payload view's | |
111 | * buffer view from the offset provided. | |
112 | */ | |
c0a66c84 JG |
113 | struct lttng_payload_view lttng_payload_view_from_view( |
114 | struct lttng_payload_view *view, size_t offset, | |
115 | ptrdiff_t len); | |
116 | ||
117 | /** | |
118 | * Return a payload view referencing a subset of a dynamic buffer. | |
119 | * | |
120 | * Meant as an adapter for code paths that need to create a payload view | |
121 | * from an existing dynamic buffer. | |
122 | * | |
123 | * @src Source dynamic buffer to reference | |
5a2f5f00 | 124 | * @offset Offset to apply to the dynamic buffer |
c0a66c84 JG |
125 | * @len Length of the buffer contents to reference. Passing -1 will |
126 | * cause the payload view to reference the whole payload from the | |
127 | * offset provided. | |
128 | */ | |
c0a66c84 JG |
129 | struct lttng_payload_view lttng_payload_view_from_dynamic_buffer( |
130 | const struct lttng_dynamic_buffer *buffer, size_t offset, | |
131 | ptrdiff_t len); | |
5a2f5f00 JG |
132 | /** |
133 | * | |
134 | * Return a payload view referencing a subset of a dynamic buffer. | |
135 | * | |
136 | * Meant as an adapter for code paths that need to create a payload view | |
137 | * from an existing buffer view. | |
138 | * | |
139 | * @src Source buffer view to reference | |
140 | * @offset Offset to apply to the buffer view | |
141 | * @len Length of the buffer contents to reference. Passing -1 will | |
142 | * cause the payload view to reference the whole payload from the | |
143 | * offset provided. | |
144 | */ | |
5a2f5f00 JG |
145 | struct lttng_payload_view lttng_payload_view_from_buffer_view( |
146 | const struct lttng_buffer_view *view, size_t offset, | |
147 | ptrdiff_t len); | |
148 | ||
e368fb43 JG |
149 | /** |
150 | * Return a payload view referencing a subset of the memory referenced by a raw | |
151 | * pointer. | |
152 | * | |
153 | * @src Source buffer to reference | |
154 | * @offset Offset to apply to the source memory buffer | |
155 | * @len Length of the memory contents to reference. | |
156 | * | |
157 | * Note that a payload view never assumes the ownership of the memory it | |
158 | * references. | |
159 | */ | |
e368fb43 JG |
160 | struct lttng_payload_view lttng_payload_view_init_from_buffer( |
161 | const char *src, size_t offset, ptrdiff_t len); | |
162 | ||
5a2f5f00 | 163 | /** |
fe489250 | 164 | * Get the number of file descriptor handles left in a payload view. |
5a2f5f00 JG |
165 | * |
166 | * @payload Payload instance | |
167 | * | |
fe489250 | 168 | * Returns the number of file descriptor handles left on success, -1 on error. |
5a2f5f00 | 169 | */ |
fe489250 | 170 | int lttng_payload_view_get_fd_handle_count( |
18eec1c9 | 171 | const struct lttng_payload_view *payload_view); |
c0a66c84 JG |
172 | |
173 | /** | |
fe489250 JG |
174 | * Pop an fd handle from a payload view. |
175 | * | |
176 | * A reference to the returned fd_handle is acquired on behalf of the caller. | |
c0a66c84 JG |
177 | * |
178 | * @payload Payload instance | |
179 | * | |
fe489250 | 180 | * Returns an fd_handle on success, -1 on error. |
c0a66c84 | 181 | */ |
fe489250 JG |
182 | struct fd_handle *lttng_payload_view_pop_fd_handle( |
183 | struct lttng_payload_view *payload_view); | |
c0a66c84 | 184 | |
7966af57 SM |
185 | #ifdef __cplusplus |
186 | } | |
187 | #endif | |
188 | ||
c0a66c84 | 189 | #endif /* LTTNG_PAYLOAD_VIEW_H */ |