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; | |
15 | ||
16 | /* | |
17 | * An lttng_payload_view references a payload and allows code to share | |
18 | * a `const` version of a subset of a payload. | |
19 | * | |
20 | * A payload view is invalidated whenever its source (a payload, or another | |
21 | * payload view) is modified. | |
22 | * | |
23 | * While a payload view does not allow users to modify the underlying bytes | |
24 | * of the payload, it can be used to 'pop' file descriptors using an iterator | |
25 | * belonging to the top-level payload view. | |
26 | * | |
27 | * Hence, a payload view created from a payload or a dynamic buffer contains | |
28 | * an implicit file descriptor iterator. Any payload view created from another | |
29 | * payload view will share the same underlying file descriptor iterator. | |
30 | * | |
31 | * The rationale for this is that a payload is never consumed directly, it | |
32 | * must be consumed through a payload view. | |
33 | * | |
34 | * Typically, a payload view will be used to rebuild a previously serialized | |
35 | * object hierarchy. Sharing an underlying iterator allows aggregate objects | |
36 | * to provide a restricted view of the payload to their members, which will | |
37 | * report the number of bytes consumed and `pop` the file descriptors they | |
38 | * should own. In return, those objects can create an even narrower view for | |
39 | * their children, allowing them to also consume file descriptors. | |
40 | * | |
41 | * Note that a payload view never assumes any ownership of the underlying | |
42 | * payload. | |
43 | */ | |
44 | struct lttng_payload_view { | |
45 | struct lttng_buffer_view buffer; | |
46 | /* private */ | |
47 | const struct lttng_dynamic_array _fds; | |
48 | struct { | |
49 | size_t *p_fds_position; | |
50 | size_t fds_position; | |
51 | } _iterator; | |
52 | }; | |
53 | ||
54 | /** | |
55 | * Return a payload view referencing a subset of a payload. | |
56 | * | |
57 | * @payload Source payload to reference | |
58 | * @offset Offset to apply to the payload's buffer | |
59 | * @len Length of the contents to reference. Passing -1 will | |
60 | * cause the view to reference the whole payload from the | |
61 | * offset provided. | |
62 | */ | |
63 | LTTNG_HIDDEN | |
64 | struct lttng_payload_view lttng_payload_view_from_payload( | |
65 | const struct lttng_payload *payload, size_t offset, | |
66 | ptrdiff_t len); | |
67 | ||
68 | /** | |
69 | * Return a payload view referencing a subset of a payload referenced by | |
70 | * another payload view. | |
71 | * | |
72 | * @view Source payload view to reference | |
73 | * @offset Offset to apply to the payload view's buffer view | |
74 | * @len Length of the contents to reference. Passing -1 will | |
75 | * cause the payload view to reference the whole payload view's | |
76 | * buffer view from the offset provided. | |
77 | */ | |
78 | LTTNG_HIDDEN | |
79 | struct lttng_payload_view lttng_payload_view_from_view( | |
80 | struct lttng_payload_view *view, size_t offset, | |
81 | ptrdiff_t len); | |
82 | ||
83 | /** | |
84 | * Return a payload view referencing a subset of a dynamic buffer. | |
85 | * | |
86 | * Meant as an adapter for code paths that need to create a payload view | |
87 | * from an existing dynamic buffer. | |
88 | * | |
89 | * @src Source dynamic buffer to reference | |
90 | * @offset Offset to apply to the payload's buffer | |
91 | * @len Length of the buffer contents to reference. Passing -1 will | |
92 | * cause the payload view to reference the whole payload from the | |
93 | * offset provided. | |
94 | */ | |
95 | LTTNG_HIDDEN | |
96 | struct lttng_payload_view lttng_payload_view_from_dynamic_buffer( | |
97 | const struct lttng_dynamic_buffer *buffer, size_t offset, | |
98 | ptrdiff_t len); | |
99 | ||
100 | /** | |
101 | * Pop an fd from a payload view. | |
102 | * No ownership of the file descriptor is assumed by the payload. | |
103 | * | |
104 | * @payload Payload instance | |
105 | * | |
106 | * Returns a file descriptor on success, -1 on error. | |
107 | */ | |
108 | LTTNG_HIDDEN | |
109 | int lttng_payload_view_pop_fd(struct lttng_payload_view *payload_view); | |
110 | ||
111 | #endif /* LTTNG_PAYLOAD_VIEW_H */ |