2 * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_PAYLOAD_VIEW_H
9 #define LTTNG_PAYLOAD_VIEW_H
11 #include <common/buffer-view.h>
12 #include <common/dynamic-array.h>
18 * An lttng_payload_view references a payload and allows code to share
19 * a `const` version of a subset of a payload.
21 * A payload view is invalidated whenever its source (a payload, or another
22 * payload view) is modified.
24 * While a payload view does not allow users to modify the underlying bytes
25 * of the payload, it can be used to 'pop' file descriptor handles using an
26 * iterator belonging to the top-level payload view.
28 * Hence, a payload view created from a payload or a dynamic buffer contains
29 * an implicit file descriptor handle iterator. Any payload view created from
30 * another payload view will share the same underlying file descriptor handle
33 * The rationale for this is that a payload is never consumed directly, it must
34 * be consumed through a payload view.
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
39 * report the number of bytes consumed and `pop` the file descriptor handle they
40 * should own. In return, those objects can create an even narrower view for
41 * their children, allowing them to also consume file descriptor handles.
43 * Note that a payload view never assumes any ownership of the underlying
46 struct lttng_payload_view
{
47 struct lttng_buffer_view buffer
;
49 const struct lttng_dynamic_pointer_array _fd_handles
;
51 size_t *p_fd_handles_position
;
52 size_t fd_handles_position
;
57 * Checks if a payload view's buffer is safe to access.
59 * After calling the payload view creation functions, callers should verify
60 * if the resquested length (if any is explicitly provided) could be mapped
63 * @view Payload to validate
66 bool lttng_payload_view_is_valid(const struct lttng_payload_view
*view
);
69 * Return a payload view referencing a subset of a payload.
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
78 struct lttng_payload_view
lttng_payload_view_from_payload(
79 const struct lttng_payload
*payload
, size_t offset
,
83 * Return a payload view referencing a subset of a payload referenced by
84 * another payload view.
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.
93 struct lttng_payload_view
lttng_payload_view_from_view(
94 struct lttng_payload_view
*view
, size_t offset
,
98 * Return a payload view referencing a subset of a dynamic buffer.
100 * Meant as an adapter for code paths that need to create a payload view
101 * from an existing dynamic buffer.
103 * @src Source dynamic buffer to reference
104 * @offset Offset to apply to the dynamic buffer
105 * @len Length of the buffer contents to reference. Passing -1 will
106 * cause the payload view to reference the whole payload from the
110 struct lttng_payload_view
lttng_payload_view_from_dynamic_buffer(
111 const struct lttng_dynamic_buffer
*buffer
, size_t offset
,
115 * Return a payload view referencing a subset of a dynamic buffer.
117 * Meant as an adapter for code paths that need to create a payload view
118 * from an existing buffer view.
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
127 struct lttng_payload_view
lttng_payload_view_from_buffer_view(
128 const struct lttng_buffer_view
*view
, size_t offset
,
132 * Return a payload view referencing a subset of the memory referenced by a raw
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.
139 * Note that a payload view never assumes the ownership of the memory it
143 struct lttng_payload_view
lttng_payload_view_init_from_buffer(
144 const char *src
, size_t offset
, ptrdiff_t len
);
147 * Get the number of file descriptor handles left in a payload view.
149 * @payload Payload instance
151 * Returns the number of file descriptor handles left on success, -1 on error.
154 int lttng_payload_view_get_fd_handle_count(
155 const struct lttng_payload_view
*payload_view
);
158 * Pop an fd handle from a payload view.
160 * A reference to the returned fd_handle is acquired on behalf of the caller.
162 * @payload Payload instance
164 * Returns an fd_handle on success, -1 on error.
167 struct fd_handle
*lttng_payload_view_pop_fd_handle(
168 struct lttng_payload_view
*payload_view
);
170 #endif /* LTTNG_PAYLOAD_VIEW_H */