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 | ||
c9e313bc SM |
11 | #include <common/buffer-view.hpp> |
12 | #include <common/dynamic-array.hpp> | |
c0a66c84 JG |
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 */ | |
7966af57 | 49 | |
b66cbf17 | 50 | const struct lttng_dynamic_pointer_array _fd_handles; |
7966af57 | 51 | |
c0a66c84 | 52 | struct { |
fe489250 JG |
53 | size_t *p_fd_handles_position; |
54 | size_t fd_handles_position; | |
c0a66c84 JG |
55 | } _iterator; |
56 | }; | |
57 | ||
3e6e0df2 JG |
58 | /** |
59 | * Checks if a payload view's buffer is safe to access. | |
60 | * | |
61 | * After calling the payload view creation functions, callers should verify | |
62 | * if the resquested length (if any is explicitly provided) could be mapped | |
63 | * to a new view. | |
b2530e4d JG |
64 | * |
65 | * @view Payload to validate | |
3e6e0df2 | 66 | */ |
3e6e0df2 JG |
67 | bool lttng_payload_view_is_valid(const struct lttng_payload_view *view); |
68 | ||
c0a66c84 JG |
69 | /** |
70 | * Return a payload view referencing a subset of a payload. | |
71 | * | |
72 | * @payload Source payload to reference | |
73 | * @offset Offset to apply to the payload's buffer | |
74 | * @len Length of the contents to reference. Passing -1 will | |
75 | * cause the view to reference the whole payload from the | |
76 | * offset provided. | |
77 | */ | |
28f23191 JG |
78 | struct lttng_payload_view |
79 | lttng_payload_view_from_payload(const struct lttng_payload *payload, size_t offset, ptrdiff_t len); | |
c0a66c84 JG |
80 | |
81 | /** | |
82 | * Return a payload view referencing a subset of a payload referenced by | |
83 | * another payload view. | |
84 | * | |
85 | * @view Source payload view to reference | |
86 | * @offset Offset to apply to the payload view's buffer view | |
87 | * @len Length of the contents to reference. Passing -1 will | |
88 | * cause the payload view to reference the whole payload view's | |
89 | * buffer view from the offset provided. | |
90 | */ | |
28f23191 JG |
91 | struct lttng_payload_view |
92 | lttng_payload_view_from_view(struct lttng_payload_view *view, size_t offset, ptrdiff_t len); | |
c0a66c84 JG |
93 | |
94 | /** | |
95 | * Return a payload view referencing a subset of a dynamic buffer. | |
96 | * | |
97 | * Meant as an adapter for code paths that need to create a payload view | |
98 | * from an existing dynamic buffer. | |
99 | * | |
100 | * @src Source dynamic buffer to reference | |
5a2f5f00 | 101 | * @offset Offset to apply to the dynamic buffer |
c0a66c84 JG |
102 | * @len Length of the buffer contents to reference. Passing -1 will |
103 | * cause the payload view to reference the whole payload from the | |
104 | * offset provided. | |
105 | */ | |
c0a66c84 | 106 | struct lttng_payload_view lttng_payload_view_from_dynamic_buffer( |
28f23191 | 107 | const struct lttng_dynamic_buffer *buffer, size_t offset, ptrdiff_t len); |
5a2f5f00 JG |
108 | /** |
109 | * | |
110 | * Return a payload view referencing a subset of a dynamic buffer. | |
111 | * | |
112 | * Meant as an adapter for code paths that need to create a payload view | |
113 | * from an existing buffer view. | |
114 | * | |
115 | * @src Source buffer view to reference | |
116 | * @offset Offset to apply to the buffer view | |
117 | * @len Length of the buffer contents to reference. Passing -1 will | |
118 | * cause the payload view to reference the whole payload from the | |
119 | * offset provided. | |
120 | */ | |
28f23191 JG |
121 | struct lttng_payload_view lttng_payload_view_from_buffer_view(const struct lttng_buffer_view *view, |
122 | size_t offset, | |
123 | ptrdiff_t len); | |
5a2f5f00 | 124 | |
e368fb43 JG |
125 | /** |
126 | * Return a payload view referencing a subset of the memory referenced by a raw | |
127 | * pointer. | |
128 | * | |
129 | * @src Source buffer to reference | |
130 | * @offset Offset to apply to the source memory buffer | |
131 | * @len Length of the memory contents to reference. | |
132 | * | |
133 | * Note that a payload view never assumes the ownership of the memory it | |
134 | * references. | |
135 | */ | |
28f23191 JG |
136 | struct lttng_payload_view |
137 | lttng_payload_view_init_from_buffer(const char *src, size_t offset, ptrdiff_t len); | |
e368fb43 | 138 | |
5a2f5f00 | 139 | /** |
fe489250 | 140 | * Get the number of file descriptor handles left in a payload view. |
5a2f5f00 JG |
141 | * |
142 | * @payload Payload instance | |
143 | * | |
fe489250 | 144 | * Returns the number of file descriptor handles left on success, -1 on error. |
5a2f5f00 | 145 | */ |
28f23191 | 146 | int lttng_payload_view_get_fd_handle_count(const struct lttng_payload_view *payload_view); |
c0a66c84 JG |
147 | |
148 | /** | |
fe489250 JG |
149 | * Pop an fd handle from a payload view. |
150 | * | |
151 | * A reference to the returned fd_handle is acquired on behalf of the caller. | |
c0a66c84 JG |
152 | * |
153 | * @payload Payload instance | |
154 | * | |
fe489250 | 155 | * Returns an fd_handle on success, -1 on error. |
c0a66c84 | 156 | */ |
28f23191 | 157 | struct fd_handle *lttng_payload_view_pop_fd_handle(struct lttng_payload_view *payload_view); |
c0a66c84 JG |
158 | |
159 | #endif /* LTTNG_PAYLOAD_VIEW_H */ |