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 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 struct lttng_payload;
  19 struct fd_handle;
  20
  21 /*
  22  * An lttng_payload_view references a payload and allows code to share
  23  * a `const` version of a subset of a payload.
  24  *
  25  * A payload view is invalidated whenever its source (a payload, or another
  26  * payload view) is modified.
  27  *
  28  * While a payload view does not allow users to modify the underlying bytes
  29  * of the payload, it can be used to 'pop' file descriptor handles using an
  30  * iterator belonging to the top-level payload view.
  31  *
  32  * Hence, a payload view created from a payload or a dynamic buffer contains
  33  * an implicit file descriptor handle iterator. Any payload view created from
  34  * another payload view will share the same underlying file descriptor handle
  35  * iterator.
  36  *
  37  * The rationale for this is that a payload is never consumed directly, it must
  38  * be consumed through a payload view.
  39  *
  40  * Typically, a payload view will be used to rebuild a previously serialized
  41  * object hierarchy. Sharing an underlying iterator allows aggregate objects
  42  * to provide a restricted view of the payload to their members, which will
  43  * report the number of bytes consumed and `pop` the file descriptor handle they
  44  * should own. In return, those objects can create an even narrower view for
  45  * their children, allowing them to also consume file descriptor handles.
  46  *
  47  * Note that a payload view never assumes any ownership of the underlying
  48  * payload.
  49  */
  50 struct lttng_payload_view {
  51         struct lttng_buffer_view buffer;
  52         /* private */
  53
  54         /*
  55          * Avoid a -Wreturn-type-c-linkage warning with clang.
  56          * gcc is more permissive with regards to this warning, but
  57          * clang is right that a structure containing a _const_ structure is not
  58          * a trivial type in the eyes of the C++ standard, theoritically affecting its
  59          * compatibility with C from an ABI standpoint:
  60          *   A trivial class is a class that is trivially copyable and has one or
  61          *   more default constructors, all of which are either trivial or deleted and
  62          *   at least one of which is not deleted.
  63          *
  64          * A const member implicitly deletes lttng_payload_view's constructor,
  65          * making it non-trivial. This is not a problem for the moment as we are
  66          * transitioning all code to C++11.
  67          */
  68 #if !defined(__cplusplus)
  69         const
  70 #endif
  71         struct lttng_dynamic_pointer_array _fd_handles;
  72
  73         struct {
  74                 size_t *p_fd_handles_position;
  75                 size_t fd_handles_position;
  76         } _iterator;
  77 };
  78
  79 /**
  80  * Checks if a payload view's buffer is safe to access.
  81  *
  82  * After calling the payload view creation functions, callers should verify
  83  * if the resquested length (if any is explicitly provided) could be mapped
  84  * to a new view.
  85  *
  86  * @view        Payload to validate
  87  */
  88 bool lttng_payload_view_is_valid(const struct lttng_payload_view *view);
  89
  90 /**
  91  * Return a payload view referencing a subset of a payload.
  92  *
  93  * @payload     Source payload to reference
  94  * @offset      Offset to apply to the payload's buffer
  95  * @len         Length of the contents to reference. Passing -1 will
  96  *              cause the view to reference the whole payload from the
  97  *              offset provided.
  98  */
  99 struct lttng_payload_view lttng_payload_view_from_payload(
 100                 const struct lttng_payload *payload, size_t offset,
 101                 ptrdiff_t len);
 102
 103 /**
 104  * Return a payload view referencing a subset of a payload referenced by
 105  * another payload view.
 106  *
 107  * @view        Source payload view to reference
 108  * @offset      Offset to apply to the payload view's buffer view
 109  * @len         Length of the contents to reference. Passing -1 will
 110  *              cause the payload view to reference the whole payload view's
 111  *              buffer view from the offset provided.
 112  */
 113 struct lttng_payload_view lttng_payload_view_from_view(
 114                 struct lttng_payload_view *view, size_t offset,
 115                 ptrdiff_t len);
 116
 117 /**
 118  * Return a payload view referencing a subset of a dynamic buffer.
 119  *
 120  * Meant as an adapter for code paths that need to create a payload view
 121  * from an existing dynamic buffer.
 122  *
 123  * @src         Source dynamic buffer to reference
 124  * @offset      Offset to apply to the dynamic buffer
 125  * @len         Length of the buffer contents to reference. Passing -1 will
 126  *              cause the payload view to reference the whole payload from the
 127  *              offset provided.
 128  */
 129 struct lttng_payload_view lttng_payload_view_from_dynamic_buffer(
 130                 const struct lttng_dynamic_buffer *buffer, size_t offset,
 131                 ptrdiff_t len);
 132 /**
 133  *
 134  * Return a payload view referencing a subset of a dynamic buffer.
 135  *
 136  * Meant as an adapter for code paths that need to create a payload view
 137  * from an existing buffer view.
 138  *
 139  * @src         Source buffer view to reference
 140  * @offset      Offset to apply to the buffer view
 141  * @len         Length of the buffer contents to reference. Passing -1 will
 142  *              cause the payload view to reference the whole payload from the
 143  *              offset provided.
 144  */
 145 struct lttng_payload_view lttng_payload_view_from_buffer_view(
 146                 const struct lttng_buffer_view *view, size_t offset,
 147                 ptrdiff_t len);
 148
 149 /**
 150  * Return a payload view referencing a subset of the memory referenced by a raw
 151  * pointer.
 152  *
 153  * @src         Source buffer to reference
 154  * @offset      Offset to apply to the source memory buffer
 155  * @len         Length of the memory contents to reference.
 156  *
 157  * Note that a payload view never assumes the ownership of the memory it
 158  * references.
 159  */
 160 struct lttng_payload_view lttng_payload_view_init_from_buffer(
 161                 const char *src, size_t offset, ptrdiff_t len);
 162
 163 /**
 164  * Get the number of file descriptor handles left in a payload view.
 165  *
 166  * @payload     Payload instance
 167  *
 168  * Returns the number of file descriptor handles left on success, -1 on error.
 169  */
 170 int lttng_payload_view_get_fd_handle_count(
 171                 const struct lttng_payload_view *payload_view);
 172
 173 /**
 174  * Pop an fd handle from a payload view.
 175  *
 176  * A reference to the returned fd_handle is acquired on behalf of the caller.
 177  *
 178  * @payload     Payload instance
 179  *
 180  * Returns an fd_handle on success, -1 on error.
 181  */
 182 struct fd_handle *lttng_payload_view_pop_fd_handle(
 183                 struct lttng_payload_view *payload_view);
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188
 189 #endif /* LTTNG_PAYLOAD_VIEW_H */