payload-view: mark lttng_payload_view_get_fd_handle_count as const
[lttng-tools.git] / src / common / payload-view.h
CommitLineData
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
14struct lttng_payload;
fe489250 15struct 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 */
46struct 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 */
65LTTNG_HIDDEN
66struct 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 */
80LTTNG_HIDDEN
81struct 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 */
97LTTNG_HIDDEN
98struct 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 */
114LTTNG_HIDDEN
115struct 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 */
130LTTNG_HIDDEN
131struct 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 */
141LTTNG_HIDDEN
fe489250 142int lttng_payload_view_get_fd_handle_count(
18eec1c9 143 const 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 */
154LTTNG_HIDDEN
fe489250
JG
155struct fd_handle *lttng_payload_view_pop_fd_handle(
156 struct lttng_payload_view *payload_view);
c0a66c84
JG
157
158#endif /* LTTNG_PAYLOAD_VIEW_H */
This page took 0.044201 seconds and 5 git commands to generate.