[lttng-tools.git] / include / lttng / destruction-handle.h

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

#ifndef LTTNG_DESTRUCTION_HANDLE_H
#define LTTNG_DESTRUCTION_HANDLE_H

#include <lttng/lttng-error.h>
#include <lttng/lttng-export.h>
#include <lttng/rotation.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@addtogroup api_session_destr_handle
@{
*/

/*!
@struct lttng_destruction_handle

@brief
    Recording session destruction handle (opaque type).
*/
struct lttng_destruction_handle;

/*!
@brief
    Return type of recording session destruction handle fuctions.

Error status enumerators have a negative value.
*/
enum lttng_destruction_handle_status {
	/// Success.
	LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,

	/// Recording session destruction operation completed.
	LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,

	/// Timeout reached.
	LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,

	/// Unsatisfied precondition.
	LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,

	/// Other error.
	LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
};

/*!
@brief
    Destroys the recording session destruction handle \lt_p{handle}.

@param[in] handle
    @parblock
    Recording session destruction handle to destroy.

    May be \c NULL.
    @endparblock
*/
LTTNG_EXPORT extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle *handle);

/*!
@brief
    Waits for the recording session destruction operation identified by
    \lt_p{handle} to complete.

If this function returns #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED,
then the recording session destruction operation identified by
\lt_p{handle} completed. This doesn't mean, however, that the
destruction operation itself succeeded; use
lttng_destruction_handle_get_result() to know this.

@param[in] handle
    Recording session destruction handle which identifies the
    destruction operation of which to wait for completion.
@param[in] timeout_ms
    Maximum time (milliseconds) to wait for the completion of the
    recording session destruction operation identified by \lt_p{handle}
    before returning #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT, or
    <code>-1</code> to wait indefinitely.

@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED
    The recording session destruction operation identified by
    \lt_p{handle} completed (with or without success).
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
    Unsatisfied precondition.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT
    The function waited for the completion of the recording session
    destruction operation for more than \lt_p{timeout_ms}&nbsp;ms.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
    Other error.

@lt_pre_not_null{handle}

@sa lttng_destruction_handle_get_result() --
    Returns whether or not a recording session destruction operation
    succeeded.
*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle *handle,
					     int timeout_ms);

/*!
@brief
    Sets \lt_p{*result} to the result of the recording session
    destruction operation identified by \lt_p{handle}.

You must successfully wait for the completion of the recording session
destruction operation identified by \lt_p{handle} with
lttng_destruction_handle_wait_for_completion() before you call this function.

On success, \lt_p{*result} is #LTTNG_OK if the destruction operation was
successful.

@param[in] handle
    Handle of the recording session destruction operation of which to
    get the result.
@param[out] result
    @parblock
    <strong>On success</strong>, this function sets \lt_p{*result} to
    the result of the recording session destruction operation identified
    by \lt_p{handle}.

    \lt_p{*result} is #LTTNG_OK if the destruction operation was
    successful.
    @endparblock

@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
    Success: \lt_p{*result} is the result of the recording session
    destruction operation identified by \lt_p{handle}.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
    Unsatisfied precondition.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
    Other error.

@lt_pre_not_null{handle}
@pre
    You successfully waited for the completion of the recording session
    destruction operation identified by \lt_p{handle} with
    lttng_destruction_handle_wait_for_completion().
@lt_pre_not_null{result}

@sa lttng_destruction_handle_wait_for_completion() --
    Waits for a recording session destruction operation to complete.
*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_result(const struct lttng_destruction_handle *handle,
				    enum lttng_error_code *result);

/*!
@brief
    Sets \lt_p{*rotation_state} to the state of a final
    \ref api_session_rotation "rotation" operation which the
    destruction of the recording session identified by \lt_p{handle}
    caused.

You must successfully wait for the completion of the recording session
destruction operation identified by \lt_p{handle} with
lttng_destruction_handle_wait_for_completion() before you call this
function.

This function is only useful if LTTng performed at least one recording
session rotation during the lifetime of the destroyed recording session.

@param[in] handle
    Handle of the destruction operation of the recording session of
    which to get the state of the final rotation operation.
@param[out] rotation_state
    @parblock
    <strong>On success</strong>, this function sets
    \lt_p{*rotation_state} to the state of the final rotation operation
    which the recording session destruction operation identified by
    \lt_p{handle} caused.

    \lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
    didn't perform any final recording session rotation.
    @endparblock

@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
    Success: \lt_p{*rotation_state} is the state of the final rotation
    of the destroyed recording session.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
    Unsatisfied precondition.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
    Other error.

@lt_pre_not_null{handle}
@pre
    You successfully waited for the completion of the recording session
    destruction operation identified by \lt_p{handle} with
    lttng_destruction_handle_wait_for_completion().
@lt_pre_not_null{rotation_state}

@sa lttng_destruction_handle_get_archive_location() --
    Get the location of the trace chunk archive which a recording
    session destruction operation created.
*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_rotation_state(const struct lttng_destruction_handle *handle,
					    enum lttng_rotation_state *rotation_state);

/*!
@brief
    Sets \lt_p{*location} to the location of the final
    \ref api_session_rotation "trace chunk archive" which
    the destruction of the recording session identified by \lt_p{handle}
    created.

You must make sure that the destruction of the recording session caused
a final, successful rotation with
lttng_destruction_handle_get_rotation_state().

This function is only useful if LTTng performed at least one recording
session rotation during the lifetime of the destroyed recording session.

@param[in] handle
    Handle of the destruction operation of the recording session of
    which to get the location of the final trace chunk archive.
@param[out] location
    @parblock
    <strong>On success</strong>, this function sets
    \lt_p{*location} to the location of the final trace chunk archive
    which the recording session destruction operation identified by
    \lt_p{handle} created.

    \lt_p{*location} is owned by \lt_p{handle}.
    @endparblock

@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
    Success: \lt_p{*location} is the location of the final trace
    chunk archive of the destroyed recording session.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
    Unsatisfied precondition.
@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
    Other error.

@lt_pre_not_null{handle}
@pre
    lttng_destruction_handle_get_rotation_state() set the
    #LTTNG_ROTATION_STATE_COMPLETED state for \lt_p{handle}.
@lt_pre_not_null{location}

@sa lttng_destruction_handle_get_rotation_state() --
    Get the state of the final rotation operation which a recording
    session destruction operation caused.
*/
LTTNG_EXPORT extern enum lttng_destruction_handle_status
lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle,
					      const struct lttng_trace_archive_location **location);

/// @}

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_DESTRUCTION_HANDLE_H */
Commit	Line	Data
3e3665b8	1	/*
ab5be9fa	2	* Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
3e3665b8	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
3e3665b8	5	*
3e3665b8 JG	6	*/
	7
	8	#ifndef LTTNG_DESTRUCTION_HANDLE_H
	9	#define LTTNG_DESTRUCTION_HANDLE_H
	10
3e3665b8	11	#include <lttng/lttng-error.h>
4bd69c5f	12	#include <lttng/lttng-export.h>
28f23191	13	#include <lttng/rotation.h>
3e3665b8 JG	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
048f01ef PP	19	/*!
	20	@addtogroup api_session_destr_handle
	21	@{
	22	*/
	23
	24	/*!
	25	@struct lttng_destruction_handle
	26
	27	@brief
	28	Recording session destruction handle (opaque type).
	29	*/
3e3665b8 JG	30	struct lttng_destruction_handle;
3e3665b8 JG	31
048f01ef PP	32	/*!
	33	@brief
	34	Return type of recording session destruction handle fuctions.
	35
	36	Error status enumerators have a negative value.
	37	*/
3e3665b8	38	enum lttng_destruction_handle_status {
048f01ef	39	/// Success.
3e3665b8	40	LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
048f01ef PP	41
048f01ef PP	42	/// Recording session destruction operation completed.
3e3665b8	43	LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
048f01ef PP	44
048f01ef PP	45	/// Timeout reached.
3e3665b8	46	LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
048f01ef PP	47
	48	/// Unsatisfied precondition.
	49	LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
	50
	51	/// Other error.
	52	LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
3e3665b8 JG	53	};
3e3665b8 JG	54
048f01ef PP	55	/*!
	56	@brief
	57	Destroys the recording session destruction handle \lt_p{handle}.
	58
	59	@param[in] handle
	60	@parblock
	61	Recording session destruction handle to destroy.
	62
	63	May be \c NULL.
	64	@endparblock
	65	*/
28f23191	66	LTTNG_EXPORT extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle *handle);
3e3665b8	67
048f01ef PP	68	/*!
	69	@brief
	70	Waits for the recording session destruction operation identified by
	71	\lt_p{handle} to complete.
	72
	73	If this function returns #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED,
	74	then the recording session destruction operation identified by
	75	\lt_p{handle} completed. This doesn't mean, however, that the
	76	destruction operation itself succeeded; use
	77	lttng_destruction_handle_get_result() to know this.
	78
	79	@param[in] handle
	80	Recording session destruction handle which identifies the
	81	destruction operation of which to wait for completion.
	82	@param[in] timeout_ms
	83	Maximum time (milliseconds) to wait for the completion of the
	84	recording session destruction operation identified by \lt_p{handle}
	85	before returning #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT, or
	86	<code>-1</code> to wait indefinitely.
	87
	88	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED
	89	The recording session destruction operation identified by
	90	\lt_p{handle} completed (with or without success).
	91	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
	92	Unsatisfied precondition.
	93	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT
	94	The function waited for the completion of the recording session
	95	destruction operation for more than \lt_p{timeout_ms} ms.
	96	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
	97	Other error.
	98
	99	@lt_pre_not_null{handle}
	100
	101	@sa lttng_destruction_handle_get_result() --
	102	Returns whether or not a recording session destruction operation
	103	succeeded.
	104	*/
4bd69c5f	105	LTTNG_EXPORT extern enum lttng_destruction_handle_status
28f23191 JG	106	lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle *handle,
28f23191 JG	107	int timeout_ms);
3e3665b8	108
048f01ef PP	109	/*!
	110	@brief
	111	Sets \lt_p{*result} to the result of the recording session
	112	destruction operation identified by \lt_p{handle}.
	113
	114	You must successfully wait for the completion of the recording session
	115	destruction operation identified by \lt_p{handle} with
	116	lttng_destruction_handle_wait_for_completion() before you call this function.
	117
	118	On success, \lt_p{*result} is #LTTNG_OK if the destruction operation was
	119	successful.
	120
	121	@param[in] handle
	122	Handle of the recording session destruction operation of which to
	123	get the result.
	124	@param[out] result
	125	@parblock
	126	<strong>On success</strong>, this function sets \lt_p{*result} to
	127	the result of the recording session destruction operation identified
	128	by \lt_p{handle}.
	129
	130	\lt_p{*result} is #LTTNG_OK if the destruction operation was
	131	successful.
	132	@endparblock
	133
	134	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
	135	Success: \lt_p{*result} is the result of the recording session
	136	destruction operation identified by \lt_p{handle}.
	137	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
	138	Unsatisfied precondition.
	139	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
	140	Other error.
	141
	142	@lt_pre_not_null{handle}
	143	@pre
	144	You successfully waited for the completion of the recording session
	145	destruction operation identified by \lt_p{handle} with
	146	lttng_destruction_handle_wait_for_completion().
	147	@lt_pre_not_null{result}
	148
	149	@sa lttng_destruction_handle_wait_for_completion() --
	150	Waits for a recording session destruction operation to complete.
	151	*/
4bd69c5f	152	LTTNG_EXPORT extern enum lttng_destruction_handle_status
28f23191 JG	153	lttng_destruction_handle_get_result(const struct lttng_destruction_handle *handle,
28f23191 JG	154	enum lttng_error_code *result);
3e3665b8	155
048f01ef PP	156	/*!
	157	@brief
	158	Sets \lt_p{*rotation_state} to the state of a final
	159	\ref api_session_rotation "rotation" operation which the
	160	destruction of the recording session identified by \lt_p{handle}
	161	caused.
	162
	163	You must successfully wait for the completion of the recording session
	164	destruction operation identified by \lt_p{handle} with
	165	lttng_destruction_handle_wait_for_completion() before you call this
	166	function.
	167
	168	This function is only useful if LTTng performed at least one recording
	169	session rotation during the lifetime of the destroyed recording session.
	170
	171	@param[in] handle
	172	Handle of the destruction operation of the recording session of
	173	which to get the state of the final rotation operation.
	174	@param[out] rotation_state
	175	@parblock
	176	<strong>On success</strong>, this function sets
	177	\lt_p{*rotation_state} to the state of the final rotation operation
	178	which the recording session destruction operation identified by
	179	\lt_p{handle} caused.
	180
	181	\lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
	182	didn't perform any final recording session rotation.
	183	@endparblock
	184
	185	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
	186	Success: \lt_p{*rotation_state} is the state of the final rotation
	187	of the destroyed recording session.
	188	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
	189	Unsatisfied precondition.
	190	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
	191	Other error.
	192
	193	@lt_pre_not_null{handle}
	194	@pre
	195	You successfully waited for the completion of the recording session
	196	destruction operation identified by \lt_p{handle} with
	197	lttng_destruction_handle_wait_for_completion().
	198	@lt_pre_not_null{rotation_state}
	199
	200	@sa lttng_destruction_handle_get_archive_location() --
	201	Get the location of the trace chunk archive which a recording
	202	session destruction operation created.
	203	*/
4bd69c5f	204	LTTNG_EXPORT extern enum lttng_destruction_handle_status
28f23191 JG	205	lttng_destruction_handle_get_rotation_state(const struct lttng_destruction_handle *handle,
28f23191 JG	206	enum lttng_rotation_state *rotation_state);
3e3665b8	207
048f01ef PP	208	/*!
	209	@brief
	210	Sets \lt_p{*location} to the location of the final
	211	\ref api_session_rotation "trace chunk archive" which
	212	the destruction of the recording session identified by \lt_p{handle}
	213	created.
	214
	215	You must make sure that the destruction of the recording session caused
	216	a final, successful rotation with
	217	lttng_destruction_handle_get_rotation_state().
	218
	219	This function is only useful if LTTng performed at least one recording
	220	session rotation during the lifetime of the destroyed recording session.
	221
	222	@param[in] handle
	223	Handle of the destruction operation of the recording session of
	224	which to get the location of the final trace chunk archive.
	225	@param[out] location
	226	@parblock
	227	<strong>On success</strong>, this function sets
	228	\lt_p{*location} to the location of the final trace chunk archive
	229	which the recording session destruction operation identified by
	230	\lt_p{handle} created.
	231
	232	\lt_p{*location} is owned by \lt_p{handle}.
	233	@endparblock
	234
	235	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
	236	Success: \lt_p{*location} is the location of the final trace
	237	chunk archive of the destroyed recording session.
	238	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
	239	Unsatisfied precondition.
	240	@retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
	241	Other error.
	242
	243	@lt_pre_not_null{handle}
	244	@pre
	245	lttng_destruction_handle_get_rotation_state() set the
	246	#LTTNG_ROTATION_STATE_COMPLETED state for \lt_p{handle}.
	247	@lt_pre_not_null{location}
	248
	249	@sa lttng_destruction_handle_get_rotation_state() --
	250	Get the state of the final rotation operation which a recording
	251	session destruction operation caused.
	252	*/
4bd69c5f	253	LTTNG_EXPORT extern enum lttng_destruction_handle_status
28f23191 JG	254	lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle,
28f23191 JG	255	const struct lttng_trace_archive_location **location);
3e3665b8	256
048f01ef PP	257	/// @}
048f01ef PP	258
4da7eebd JG	259	#ifdef __cplusplus
	260	}
	261	#endif
	262
3e3665b8	263	#endif /* LTTNG_DESTRUCTION_HANDLE_H */