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