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 | ||
14 | struct lttng_payload; | |
fe489250 | 15 | struct fd_handle; |
c0a66c84 JG |
16 | |
17 | /* | |
18 | * An lttng_payload_view references a payload and allows code to share | |
19 | * a `const` version of a subset of a payload. | |
20 | * | |
21 | * A payload view is invalidated whenever its source (a payload, or another | |
22 | * payload view) is modified. | |
23 | * | |
24 | * While a payload view does not allow users to modify the underlying bytes | |
fe489250 JG |
25 | * of the payload, it can be used to 'pop' file descriptor handles using an |
26 | * iterator belonging to the top-level payload view. | |
c0a66c84 JG |
27 | * |
28 | * Hence, a payload view created from a payload or a dynamic buffer contains | |
fe489250 JG |
29 | * an implicit file descriptor handle iterator. Any payload view created from |
30 | * another payload view will share the same underlying file descriptor handle | |
31 | * iterator. | |
c0a66c84 | 32 | * |
fe489250 JG |
33 | * The rationale for this is that a payload is never consumed directly, it must |
34 | * be consumed through a payload view. | |
c0a66c84 JG |
35 | * |
36 | * Typically, a payload view will be used to rebuild a previously serialized | |
37 | * object hierarchy. Sharing an underlying iterator allows aggregate objects | |
38 | * to provide a restricted view of the payload to their members, which will | |
fe489250 | 39 | * report the number of bytes consumed and `pop` the file descriptor handle they |
c0a66c84 | 40 | * should own. In return, those objects can create an even narrower view for |
fe489250 | 41 | * their children, allowing them to also consume file descriptor handles. |
c0a66c84 JG |
42 | * |
43 | * Note that a payload view never assumes any ownership of the underlying | |
44 | * payload. | |
45 | */ | |
46 | struct lttng_payload_view { | |
47 | struct lttng_buffer_view buffer; | |
48 | /* private */ | |
fe489250 | 49 | const struct lttng_dynamic_pointer_array _fd_handles; |
c0a66c84 | 50 | struct { |
fe489250 JG |
51 | size_t *p_fd_handles_position; |
52 | size_t fd_handles_position; | |
c0a66c84 JG |
53 | } _iterator; |
54 | }; | |
55 | ||
3e6e0df2 JG |
56 | /** |
57 | * Checks if a payload view's buffer is safe to access. | |
58 | * | |
59 | * After calling the payload view creation functions, callers should verify | |
60 | * if the resquested length (if any is explicitly provided) could be mapped | |
61 | * to a new view. | |
b2530e4d JG |
62 | * |
63 | * @view Payload to validate | |
3e6e0df2 JG |
64 | */ |
65 | LTTNG_HIDDEN | |
66 | bool lttng_payload_view_is_valid(const struct lttng_payload_view *view); | |
67 | ||
c0a66c84 JG |
68 | /** |
69 | * Return a payload view referencing a subset of a payload. | |
70 | * | |
71 | * @payload Source payload to reference | |
72 | * @offset Offset to apply to the payload's buffer | |
73 | * @len Length of the contents to reference. Passing -1 will | |
74 | * cause the view to reference the whole payload from the | |
75 | * offset provided. | |
76 | */ | |
77 | LTTNG_HIDDEN | |
78 | struct lttng_payload_view lttng_payload_view_from_payload( | |
79 | const struct lttng_payload *payload, size_t offset, | |
80 | ptrdiff_t len); | |
81 | ||
82 | /** | |
83 | * Return a payload view referencing a subset of a payload referenced by | |
84 | * another payload view. | |
85 | * | |
86 | * @view Source payload view to reference | |
87 | * @offset Offset to apply to the payload view's buffer view | |
88 | * @len Length of the contents to reference. Passing -1 will | |
89 | * cause the payload view to reference the whole payload view's | |
90 | * buffer view from the offset provided. | |
91 | */ | |
92 | LTTNG_HIDDEN | |
93 | struct lttng_payload_view lttng_payload_view_from_view( | |
94 | struct lttng_payload_view *view, size_t offset, | |
95 | ptrdiff_t len); | |
96 | ||
97 | /** | |
98 | * Return a payload view referencing a subset of a dynamic buffer. | |
99 | * | |
100 | * Meant as an adapter for code paths that need to create a payload view | |
101 | * from an existing dynamic buffer. | |
102 | * | |
103 | * @src Source dynamic buffer to reference | |
5a2f5f00 | 104 | * @offset Offset to apply to the dynamic buffer |
c0a66c84 JG |
105 | * @len Length of the buffer contents to reference. Passing -1 will |
106 | * cause the payload view to reference the whole payload from the | |
107 | * offset provided. | |
108 | */ | |
109 | LTTNG_HIDDEN | |
110 | struct lttng_payload_view lttng_payload_view_from_dynamic_buffer( | |
111 | const struct lttng_dynamic_buffer *buffer, size_t offset, | |
112 | ptrdiff_t len); | |
5a2f5f00 JG |
113 | /** |
114 | * | |
115 | * Return a payload view referencing a subset of a dynamic buffer. | |
116 | * | |
117 | * Meant as an adapter for code paths that need to create a payload view | |
118 | * from an existing buffer view. | |
119 | * | |
120 | * @src Source buffer view to reference | |
121 | * @offset Offset to apply to the buffer view | |
122 | * @len Length of the buffer contents to reference. Passing -1 will | |
123 | * cause the payload view to reference the whole payload from the | |
124 | * offset provided. | |
125 | */ | |
126 | LTTNG_HIDDEN | |
127 | struct lttng_payload_view lttng_payload_view_from_buffer_view( | |
128 | const struct lttng_buffer_view *view, size_t offset, | |
129 | ptrdiff_t len); | |
130 | ||
e368fb43 JG |
131 | /** |
132 | * Return a payload view referencing a subset of the memory referenced by a raw | |
133 | * pointer. | |
134 | * | |
135 | * @src Source buffer to reference | |
136 | * @offset Offset to apply to the source memory buffer | |
137 | * @len Length of the memory contents to reference. | |
138 | * | |
139 | * Note that a payload view never assumes the ownership of the memory it | |
140 | * references. | |
141 | */ | |
142 | LTTNG_HIDDEN | |
143 | struct lttng_payload_view lttng_payload_view_init_from_buffer( | |
144 | const char *src, size_t offset, ptrdiff_t len); | |
145 | ||
5a2f5f00 | 146 | /** |
fe489250 | 147 | * Get the number of file descriptor handles left in a payload view. |
5a2f5f00 JG |
148 | * |
149 | * @payload Payload instance | |
150 | * | |
fe489250 | 151 | * Returns the number of file descriptor handles left on success, -1 on error. |
5a2f5f00 JG |
152 | */ |
153 | LTTNG_HIDDEN | |
fe489250 | 154 | int lttng_payload_view_get_fd_handle_count( |
18eec1c9 | 155 | const struct lttng_payload_view *payload_view); |
c0a66c84 JG |
156 | |
157 | /** | |
fe489250 JG |
158 | * Pop an fd handle from a payload view. |
159 | * | |
160 | * A reference to the returned fd_handle is acquired on behalf of the caller. | |
c0a66c84 JG |
161 | * |
162 | * @payload Payload instance | |
163 | * | |
fe489250 | 164 | * Returns an fd_handle on success, -1 on error. |
c0a66c84 JG |
165 | */ |
166 | LTTNG_HIDDEN | |
fe489250 JG |
167 | struct fd_handle *lttng_payload_view_pop_fd_handle( |
168 | struct lttng_payload_view *payload_view); | |
c0a66c84 JG |
169 | |
170 | #endif /* LTTNG_PAYLOAD_VIEW_H */ |