src/common/payload-view.h

   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 struct fd_handle;
  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
  25  * of the payload, it can be used to 'pop' file descriptor handles using an
  26  * iterator belonging to the top-level payload view.
  27  *
  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
  31  * iterator.
  32  *
  33  * The rationale for this is that a payload is never consumed directly, it must
  34  * be consumed through a payload view.
  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
  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.
  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 */
  49         const struct lttng_dynamic_pointer_array _fd_handles;
  50         struct {
  51                 size_t *p_fd_handles_position;
  52                 size_t fd_handles_position;
  53         } _iterator;
  54 };
  55
  56 /**
  57  * Checks if a payload view's buffer is safe to access.
  58  *
  59  * After calling the payload view creation functions, callers should verify
  60  * if the resquested length (if any is explicitly provided) could be mapped
  61  * to a new view.
  62  *
  63  * @view        Payload to validate
  64  */
  65 LTTNG_HIDDEN
  66 bool lttng_payload_view_is_valid(const struct lttng_payload_view *view);
  67
  68 /**
  69  * Return a payload view referencing a subset of a payload.
  70  *
  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
  75  *              offset provided.
  76  */
  77 LTTNG_HIDDEN
  78 struct lttng_payload_view lttng_payload_view_from_payload(
  79                 const struct lttng_payload *payload, size_t offset,
  80                 ptrdiff_t len);
  81
  82 /**
  83  * Return a payload view referencing a subset of a payload referenced by
  84  * another payload view.
  85  *
  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.
  91  */
  92 LTTNG_HIDDEN
  93 struct lttng_payload_view lttng_payload_view_from_view(
  94                 struct lttng_payload_view *view, size_t offset,
  95                 ptrdiff_t len);
  96
  97 /**
  98  * Return a payload view referencing a subset of a dynamic buffer.
  99  *
 100  * Meant as an adapter for code paths that need to create a payload view
 101  * from an existing dynamic buffer.
 102  *
 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
 107  *              offset provided.
 108  */
 109 LTTNG_HIDDEN
 110 struct lttng_payload_view lttng_payload_view_from_dynamic_buffer(
 111                 const struct lttng_dynamic_buffer *buffer, size_t offset,
 112                 ptrdiff_t len);
 113 /**
 114  *
 115  * Return a payload view referencing a subset of a dynamic buffer.
 116  *
 117  * Meant as an adapter for code paths that need to create a payload view
 118  * from an existing buffer view.
 119  *
 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
 124  *              offset provided.
 125  */
 126 LTTNG_HIDDEN
 127 struct lttng_payload_view lttng_payload_view_from_buffer_view(
 128                 const struct lttng_buffer_view *view, size_t offset,
 129                 ptrdiff_t len);
 130
 131 /**
 132  * Return a payload view referencing a subset of the memory referenced by a raw
 133  * pointer.
 134  *
 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.
 138  *
 139  * Note that a payload view never assumes the ownership of the memory it
 140  * references.
 141  */
 142 LTTNG_HIDDEN
 143 struct lttng_payload_view lttng_payload_view_init_from_buffer(
 144                 const char *src, size_t offset, ptrdiff_t len);
 145
 146 /**
 147  * Get the number of file descriptor handles left in a payload view.
 148  *
 149  * @payload     Payload instance
 150  *
 151  * Returns the number of file descriptor handles left on success, -1 on error.
 152  */
 153 LTTNG_HIDDEN
 154 int lttng_payload_view_get_fd_handle_count(
 155                 const struct lttng_payload_view *payload_view);
 156
 157 /**
 158  * Pop an fd handle from a payload view.
 159  *
 160  * A reference to the returned fd_handle is acquired on behalf of the caller.
 161  *
 162  * @payload     Payload instance
 163  *
 164  * Returns an fd_handle on success, -1 on error.
 165  */
 166 LTTNG_HIDDEN
 167 struct fd_handle *lttng_payload_view_pop_fd_handle(
 168                 struct lttng_payload_view *payload_view);
 169
 170 #endif /* LTTNG_PAYLOAD_VIEW_H */