[lttng-tools.git] / src / common / trace-chunk-registry.hpp

/*
 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_TRACE_CHUNK_REGISTRY_H
#define LTTNG_TRACE_CHUNK_REGISTRY_H

#include <common/macros.hpp>
#include <common/trace-chunk.hpp>

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

struct lttng_trace_chunk_registry;

/*
 * Create an lttng_trace_chunk registry.
 *
 * A trace chunk registry maintains an association between a
 * (session_id, chunk_id) tuple and a trace chunk object. The chunk_id can
 * be "unset" in the case of an anonymous trace chunk.
 *
 * Note that a trace chunk registry holds no ownership of its trace
 * chunks. Trace chunks are unpublished when their last reference is released.
 * See the documentation of lttng_trace_chunk.
 *
 * Returns a trace chunk registry on success, NULL on error.
 *
 * Note that a trace chunk registry may only be accessed by an RCU thread.
 */
struct lttng_trace_chunk_registry *lttng_trace_chunk_registry_create();

/*
 * Destroy an lttng trace chunk registry. The registry must be emptied
 * (i.e. all references to the trace chunks it contains must be released) before
 * it is destroyed.
 */
void lttng_trace_chunk_registry_destroy(struct lttng_trace_chunk_registry *registry);

/*
 * Publish a trace chunk for a given session id.
 * A reference is acquired on behalf of the caller.
 *
 * The trace chunk that is returned is the published version of the trace
 * chunk. The chunk provided should be discarded on success and it's
 * published version used in its place.
 *
 * See the documentation of lttng_trace_chunk for more information on
 * the usage of the various parameters.
 *
 * Returns an lttng_trace_chunk on success, NULL on error.
 */
struct lttng_trace_chunk *
lttng_trace_chunk_registry_publish_chunk(struct lttng_trace_chunk_registry *registry,
					 uint64_t session_id,
					 struct lttng_trace_chunk *chunk);
/*
 * Adds the `previously_published` parameter which allows the caller
 * to know if a trace chunk equivalent to `chunk` was previously published.
 *
 * The registry holds a reference to the published trace chunks it contains.
 * Trace chunks automatically unpublish themselves from their registry on
 * destruction.
 *
 * This information is necessary to drop the reference of newly published
 * chunks when a user doesn't wish to explicitly maintain all references
 * to a given trace chunk.
 *
 * For instance, the relay daemon doesn't need the registry to hold a
 * reference since it controls the lifetime of its trace chunks.
 * Conversely, the consumer daemons rely on the session daemon to inform
 * them of the end of life of a trace chunk and the trace chunks don't
 * belong to a specific top-level object: they are always retrieved from
 * the registry by `id`.
 */
struct lttng_trace_chunk *
lttng_trace_chunk_registry_publish_chunk(struct lttng_trace_chunk_registry *registry,
					 uint64_t session_id,
					 struct lttng_trace_chunk *chunk,
					 bool *previously_published);

/*
 * Look-up a trace chunk by session_id and chunk_id.
 * A reference is acquired on behalf of the caller.
 *
 * Returns an lttng_trace_chunk on success, NULL if the chunk does not exist.
 */
struct lttng_trace_chunk *lttng_trace_chunk_registry_find_chunk(
	const struct lttng_trace_chunk_registry *registry, uint64_t session_id, uint64_t chunk_id);

/*
 * Query the existence of a trace chunk by session_id and chunk_id.
 *
 * Returns 0 on success, a negative value on error.
 */
int lttng_trace_chunk_registry_chunk_exists(const struct lttng_trace_chunk_registry *registry,
					    uint64_t session_id,
					    uint64_t chunk_id,
					    bool *chunk_exists);

/*
 * Look-up an anonymous trace chunk by session_id.
 * A reference is acquired on behalf of the caller.
 *
 * Returns an lttng_trace_chunk on success, NULL if the chunk does not exist.
 */
struct lttng_trace_chunk *
lttng_trace_chunk_registry_find_anonymous_chunk(const struct lttng_trace_chunk_registry *registry,
						uint64_t session_id);

unsigned int
lttng_trace_chunk_registry_put_each_chunk(const struct lttng_trace_chunk_registry *registry);

#endif /* LTTNG_TRACE_CHUNK_REGISTRY_H */
Commit	Line	Data
	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 */