lttng-ctl: Expose sessiond cmd_clear_session command

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

diff --git a/include/lttng/clear-handle.h b/include/lttng/clear-handle.h
new file mode 100644 (file)
index 0000000..ea9edd4
--- /dev/null
+++ b/include/lttng/clear-handle.h
@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
+ * Copyright (C) 2019 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
+ *
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License, version 2.1 only,
+ * as published by the Free Software Foundation.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef LTTNG_CLEAR_HANDLE_H
+#define LTTNG_CLEAR_HANDLE_H
+
+#include <lttng/lttng-error.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.
+ */
+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.
+ */
+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).
+ */
+extern enum lttng_clear_handle_status
+       lttng_clear_handle_get_result(
+               const struct lttng_clear_handle *handle,
+               enum lttng_error_code *result);
+
+#endif /* LTTNG_CLEAR_HANDLE_H */