X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Frotation.h;h=05216fc37629b7f29f7de657e2263112b0a572ab;hp=47ca2571591d2a3d787d3447887d2748a3e782ec;hb=d68c9a04537b683991a7355b812b0af954008cf1;hpb=d88744a44aa5f2ca90ab87946692b9eed3120641

diff --git a/include/lttng/rotation.h b/include/lttng/rotation.h
index 47ca25715..05216fc37 100644
--- a/include/lttng/rotation.h
+++ b/include/lttng/rotation.h
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2017 - Julien Desfossez <jdesfossez@efficios.com>
+ * Copyright (C) 2018 - Jérémie Galarneau <jeremie.galarneau@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,
@@ -25,32 +26,130 @@ extern "C" {
 #endif
 
 /*
- * Return codes for lttng_rotate_session_get_output_path.
+ * Return codes for lttng_rotation_handle_get_state()
  */
-enum lttng_rotation_status {
-	/*
-	 * After starting a rotation.
-	 */
-	LTTNG_ROTATION_STATUS_STARTED = 0,
+enum lttng_rotation_state {
 	/*
-	 * When the rotation is complete.
+	 * Rotation is ongoing, but has not been completed yet.
 	 */
-	LTTNG_ROTATION_STATUS_COMPLETED = 1,
+	LTTNG_ROTATION_STATE_ONGOING = 0,
 	/*
-	 * If the handle does not match the last rotate command, we cannot
-	 * retrieve the path for the chunk.
+	 * Rotation has been completed and the resulting chunk
+	 * can now safely be read.
 	 */
-	LTTNG_ROTATION_STATUS_EXPIRED = 2,
+	LTTNG_ROTATION_STATE_COMPLETED = 1,
 	/*
-	 * On error.
+	 * The rotation has expired.
+	 *
+	 * The information associated with a given rotation is eventually
+	 * purged by the session daemon. In such a case, the attributes of
+	 * the rotation, such as its path, may no longer be available.
+	 *
+	 * Note that this state does not guarantee the the rotation was
+	 * completed successfully.
 	 */
-	LTTNG_ROTATION_STATUS_ERROR = 3,
+	LTTNG_ROTATION_STATE_EXPIRED = 2,
 	/*
-	 * If no rotation occured during this session.
+	 * The rotation could not be completed due to an error.
 	 */
-	LTTNG_ROTATION_STATUS_NO_ROTATION = 4,
+	LTTNG_ROTATION_STATE_ERROR = 3,
+};
+
+enum lttng_rotation_status {
+	LTTNG_ROTATION_STATUS_OK = 0,
+	/* Information not available. */
+	LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
+	/* Generic error. */
+	LTTNG_ROTATION_STATUS_ERROR = -1,
+	/* Invalid parameters provided. */
+	LTTNG_ROTATION_STATUS_INVALID = -2,
 };
 
+/*
+ * Input parameter to the lttng_rotate_session command.
+ *
+ * An immediate rotation is performed as soon as possible by the tracers.
+ *
+ * The lttng_rotation_immediate_attr object is opaque to the user. Use the
+ * helper functions below to access it.
+ */
+struct lttng_rotation_immediate_attr;
+
+/*
+ * Handle used to represent a specific rotation.
+ *
+ * This object is opaque to the user. Use the helper functions below to access
+ * it.
+ */
+struct lttng_rotation_handle;
+
+/*
+ * Return a newly allocated immediate session rotation descriptor object or NULL
+ * on error.
+ */
+extern struct lttng_rotation_immediate_attr *
+lttng_rotation_immediate_attr_create(void);
+
+/*
+ * Destroy a given immediate session rotation descriptor object.
+ */
+extern void lttng_rotation_immediate_attr_destroy(
+		struct lttng_rotation_immediate_attr *attr);
+
+/*
+ * Set the name of the session to rotate immediately.
+ *
+ * The session_name parameter is copied to the immediate session rotation
+ * attributes.
+ */
+extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name(
+		struct lttng_rotation_immediate_attr *attr,
+		const char *session_name);
+
+/*
+ * Get the current state of the rotation referenced by the handle.
+ *
+ * This will issue a request to the session daemon on every call. Hence,
+ * the result of this call may change over time.
+ */
+extern enum lttng_rotation_status lttng_rotation_handle_get_state(
+		struct lttng_rotation_handle *rotation_handle,
+		enum lttng_rotation_state *rotation_state);
+
+/*
+ * Get the location of the rotation's resulting archive.
+ *
+ * The rotation must be completed in order for this call to succeed.
+ * The path returned is owned by the rotation handle.
+ *
+ * Note that path will not be set in case of error, or if the session
+ * rotation has expired.
+ *
+ * FIXME: Return an lttng_location object instead of a path.
+ */
+extern enum lttng_rotation_status lttng_rotation_handle_get_completed_archive_location(
+		struct lttng_rotation_handle *rotation_handle,
+		const char **path);
+
+/*
+ * Destroy an lttng_rotate_session handle.
+ */
+extern void lttng_rotation_handle_destroy(
+		struct lttng_rotation_handle *rotation_handle);
+
+/*
+ * Rotate the output folder of the session
+ *
+ * On success, handle is allocated and can be used to monitor the progress
+ * of the rotation with lttng_rotation_get_state(). The handle must be freed
+ * by the caller with lttng_rotation_handle_destroy().
+ *
+ * Return 0 if the rotate action was successfully launched or a negative
+ * LTTng error code on error.
+ */
+extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr,
+		struct lttng_rotation_handle **rotation_handle);
+
 #ifdef __cplusplus
 }
 #endif