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

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

#ifndef LTTNG_CLEAR_HANDLE_H
#define LTTNG_CLEAR_HANDLE_H

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

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Handle used to represent a specific instance of session clear
 * operation.
 */
struct lttng_clear_handle;

/*
 * Negative values indicate errors. Values >= 0 indicate success.
 */
enum lttng_clear_handle_status {
	LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
	LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
	LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
	LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
	LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
};

/*
 * Destroy an lttng_clear_handle.
 * The handle should be discarded after this call.
 */
LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);

/*
 * Wait for a session clear operation to complete.
 *
 * A negative timeout_ms value can be used to wait indefinitely.
 *
 * Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
 * operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
 * to indicate that the wait timed out.
 * On error, one of the negative lttng_clear_handle_status is returned.
 *
 * Note: This function returning a success status does not mean that
 * the clear operation itself succeeded; it indicates that the _wait_
 * operation completed successfully.
 */
LTTNG_EXPORT extern enum lttng_clear_handle_status
	lttng_clear_handle_wait_for_completion(
		struct lttng_clear_handle *handle, int timeout_ms);

/*
 * Get the result of a session clear operation.
 *
 * This function must be used on a clear handle which was successfully waited
 * on.
 *
 * Returns LTTNG_CLEAR_HANDLE_STATUS_OK if the result of the session
 * clear operation could be obtained. Check the value of 'result' to
 * determine if the session clear operation completed successfully or not.
 *
 * On error, one of the negative lttng_clear_handle_status is returned.
 * Returns LTTNG_CLEAR_HANDLE_STATUS_INVALID if the clear operation
 * was not waited-on using the handle or if the arguments of the function are
 * invalid (e.g. NULL).
 */
LTTNG_EXPORT extern enum lttng_clear_handle_status
	lttng_clear_handle_get_result(
		const struct lttng_clear_handle *handle,
		enum lttng_error_code *result);
#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CLEAR_HANDLE_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	* Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	4	*
	5	* SPDX-License-Identifier: LGPL-2.1-only
	6	*
	7	*/
	8
	9	#ifndef LTTNG_CLEAR_HANDLE_H
	10	#define LTTNG_CLEAR_HANDLE_H
	11
	12	#include <lttng/lttng-error.h>
	13	#include <lttng/lttng-export.h>
	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
	19	/*
	20	* Handle used to represent a specific instance of session clear
	21	* operation.
	22	*/
	23	struct lttng_clear_handle;
	24
	25	/*
	26	* Negative values indicate errors. Values >= 0 indicate success.
	27	*/
	28	enum lttng_clear_handle_status {
	29	LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
	30	LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
	31	LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
	32	LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
	33	LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
	34	};
	35
	36	/*
	37	* Destroy an lttng_clear_handle.
	38	* The handle should be discarded after this call.
	39	*/
	40	LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);
	41
	42	/*
	43	* Wait for a session clear operation to complete.
	44	*
	45	* A negative timeout_ms value can be used to wait indefinitely.
	46	*
	47	* Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
	48	* operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
	49	* to indicate that the wait timed out.
	50	* On error, one of the negative lttng_clear_handle_status is returned.
	51	*
	52	* Note: This function returning a success status does not mean that
	53	* the clear operation itself succeeded; it indicates that the _wait_
	54	* operation completed successfully.
	55	*/
	56	LTTNG_EXPORT extern enum lttng_clear_handle_status
	57	lttng_clear_handle_wait_for_completion(
	58	struct lttng_clear_handle *handle, int timeout_ms);
	59
	60	/*
	61	* Get the result of a session clear operation.
	62	*
	63	* This function must be used on a clear handle which was successfully waited
	64	* on.
	65	*
	66	* Returns LTTNG_CLEAR_HANDLE_STATUS_OK if the result of the session
	67	* clear operation could be obtained. Check the value of 'result' to
	68	* determine if the session clear operation completed successfully or not.
	69	*
	70	* On error, one of the negative lttng_clear_handle_status is returned.
	71	* Returns LTTNG_CLEAR_HANDLE_STATUS_INVALID if the clear operation
	72	* was not waited-on using the handle or if the arguments of the function are
	73	* invalid (e.g. NULL).
	74	*/
	75	LTTNG_EXPORT extern enum lttng_clear_handle_status
	76	lttng_clear_handle_get_result(
	77	const struct lttng_clear_handle *handle,
	78	enum lttng_error_code *result);
	79	#ifdef __cplusplus
	80	}
	81	#endif
	82
	83	#endif /* LTTNG_CLEAR_HANDLE_H */