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
  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 */