src/common/trace-chunk-registry.hpp

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_TRACE_CHUNK_REGISTRY_H
   9 #define LTTNG_TRACE_CHUNK_REGISTRY_H
  10
  11 #include <common/macros.hpp>
  12 #include <common/trace-chunk.hpp>
  13
  14 #include <stdbool.h>
  15 #include <stddef.h>
  16 #include <stdint.h>
  17
  18 struct lttng_trace_chunk_registry;
  19
  20 /*
  21  * Create an lttng_trace_chunk registry.
  22  *
  23  * A trace chunk registry maintains an association between a
  24  * (session_id, chunk_id) tuple and a trace chunk object. The chunk_id can
  25  * be "unset" in the case of an anonymous trace chunk.
  26  *
  27  * Note that a trace chunk registry holds no ownership of its trace
  28  * chunks. Trace chunks are unpublished when their last reference is released.
  29  * See the documentation of lttng_trace_chunk.
  30  *
  31  * Returns a trace chunk registry on success, NULL on error.
  32  *
  33  * Note that a trace chunk registry may only be accessed by an RCU thread.
  34  */
  35 struct lttng_trace_chunk_registry *lttng_trace_chunk_registry_create();
  36
  37 /*
  38  * Destroy an lttng trace chunk registry. The registry must be emptied
  39  * (i.e. all references to the trace chunks it contains must be released) before
  40  * it is destroyed.
  41  */
  42 void lttng_trace_chunk_registry_destroy(struct lttng_trace_chunk_registry *registry);
  43
  44 /*
  45  * Publish a trace chunk for a given session id.
  46  * A reference is acquired on behalf of the caller.
  47  *
  48  * The trace chunk that is returned is the published version of the trace
  49  * chunk. The chunk provided should be discarded on success and it's
  50  * published version used in its place.
  51  *
  52  * See the documentation of lttng_trace_chunk for more information on
  53  * the usage of the various parameters.
  54  *
  55  * Returns an lttng_trace_chunk on success, NULL on error.
  56  */
  57 struct lttng_trace_chunk *
  58 lttng_trace_chunk_registry_publish_chunk(struct lttng_trace_chunk_registry *registry,
  59                                          uint64_t session_id,
  60                                          struct lttng_trace_chunk *chunk);
  61 /*
  62  * Adds the `previously_published` parameter which allows the caller
  63  * to know if a trace chunk equivalent to `chunk` was previously published.
  64  *
  65  * The registry holds a reference to the published trace chunks it contains.
  66  * Trace chunks automatically unpublish themselves from their registry on
  67  * destruction.
  68  *
  69  * This information is necessary to drop the reference of newly published
  70  * chunks when a user doesn't wish to explicitly maintain all references
  71  * to a given trace chunk.
  72  *
  73  * For instance, the relay daemon doesn't need the registry to hold a
  74  * reference since it controls the lifetime of its trace chunks.
  75  * Conversely, the consumer daemons rely on the session daemon to inform
  76  * them of the end of life of a trace chunk and the trace chunks don't
  77  * belong to a specific top-level object: they are always retrieved from
  78  * the registry by `id`.
  79  */
  80 struct lttng_trace_chunk *
  81 lttng_trace_chunk_registry_publish_chunk(struct lttng_trace_chunk_registry *registry,
  82                                          uint64_t session_id,
  83                                          struct lttng_trace_chunk *chunk,
  84                                          bool *previously_published);
  85
  86 /*
  87  * Look-up a trace chunk by session_id and chunk_id.
  88  * A reference is acquired on behalf of the caller.
  89  *
  90  * Returns an lttng_trace_chunk on success, NULL if the chunk does not exist.
  91  */
  92 struct lttng_trace_chunk *lttng_trace_chunk_registry_find_chunk(
  93         const struct lttng_trace_chunk_registry *registry, uint64_t session_id, uint64_t chunk_id);
  94
  95 /*
  96  * Query the existence of a trace chunk by session_id and chunk_id.
  97  *
  98  * Returns 0 on success, a negative value on error.
  99  */
 100 int lttng_trace_chunk_registry_chunk_exists(const struct lttng_trace_chunk_registry *registry,
 101                                             uint64_t session_id,
 102                                             uint64_t chunk_id,
 103                                             bool *chunk_exists);
 104
 105 /*
 106  * Look-up an anonymous trace chunk by session_id.
 107  * A reference is acquired on behalf of the caller.
 108  *
 109  * Returns an lttng_trace_chunk on success, NULL if the chunk does not exist.
 110  */
 111 struct lttng_trace_chunk *
 112 lttng_trace_chunk_registry_find_anonymous_chunk(const struct lttng_trace_chunk_registry *registry,
 113                                                 uint64_t session_id);
 114
 115 unsigned int
 116 lttng_trace_chunk_registry_put_each_chunk(const struct lttng_trace_chunk_registry *registry);
 117
 118 #endif /* LTTNG_TRACE_CHUNK_REGISTRY_H */