X-Git-Url: https://git.liburcu.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fclear-handle.h;fp=include%2Flttng%2Fclear-handle.h;h=9a8048456421e5b7a62f2097e887094bcde82a13;hp=4fc5695ed9a77d8caf3355d0b81e47e107f0766a;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b
diff --git a/include/lttng/clear-handle.h b/include/lttng/clear-handle.h
index 4fc5695ed..9a8048456 100644
--- a/include/lttng/clear-handle.h
+++ b/include/lttng/clear-handle.h
@@ -16,64 +16,143 @@
extern "C" {
#endif
-/*
- * Handle used to represent a specific instance of session clear
- * operation.
- */
+/*!
+@addtogroup api_session_clear
+@{
+*/
+
+/*!
+@struct lttng_clear_handle
+
+@brief
+ \lt_obj_c_session clearing handle (opaque type).
+*/
struct lttng_clear_handle;
-/*
- * Negative values indicate errors. Values >= 0 indicate success.
- */
+/*!
+@brief
+ Return type of \lt_obj_session clearing handle functions.
+
+Error status enumerators have a negative value.
+*/
enum lttng_clear_handle_status {
- LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
- LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
+ /// Success.
LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
+
+ /// Recording session clearing operation completed.
LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
+
+ /// Timeout reached.
LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
+
+ /// Unsatisfied precondition.
+ LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
+
+ /// Other error.
+ LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
};
-/*
- * Destroy an lttng_clear_handle.
- * The handle should be discarded after this call.
- */
+/*!
+@brief
+ Destroys the \lt_obj_session clearing handle \lt_p{handle}.
+
+@param[in] handle
+ @parblock
+ Recording session clearing handle to destroy.
+
+ May be \c NULL.
+ @endparblock
+*/
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.
- */
+/*!
+@brief
+ Waits for the \lt_obj_session clearing operation identified by
+ \lt_p{handle} to complete.
+
+If this function returns #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED, then the
+recording session clearing operation identified by \lt_p{handle}
+completed. This doesn't mean, however, that the clearing operation
+itself succeeded; use lttng_clear_handle_get_result() to know this.
+
+@param[in] handle
+ Recording session clearing handle which identifies the clearing
+ operation of which to wait for completion.
+@param[in] timeout_ms
+ Maximum time (milliseconds) to wait for the completion of the
+ recording session clearing operation identified by \lt_p{handle}
+ before returning #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT, or
+ -1 to wait indefinitely.
+
+@retval #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED
+ The recording session clearing operation identified by \lt_p{handle}
+ completed (with or without success).
+@retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT
+ The function waited for the completion of the recording session
+ clearing operation for more than \lt_p{timeout_ms} ms.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+
+@sa lttng_clear_handle_get_result() --
+ Returns whether or not a recording session clearing operation
+ succeeded.
+*/
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).
- */
+/*!
+@brief
+ Sets \lt_p{*result} to the result of the \lt_obj_session clearing
+ operation identified by \lt_p{handle}.
+
+You must successfully wait for the completion of the recording session
+clearing operation identified by \lt_p{handle} with
+lttng_clear_handle_wait_for_completion() before you call this function.
+
+On success, \lt_p{*result} is #LTTNG_OK if the clearing operation was
+successful.
+
+@param[in] handle
+ Handle of the recording session clearing operation of which to get
+ the result.
+@param[out] result
+ @parblock
+ On success, this function sets \lt_p{*result} to
+ the result of the recording session clearing operation identified by
+ \lt_p{handle}.
+
+ \lt_p{*result} is #LTTNG_OK if the clearing operation was
+ successful.
+ @endparblock
+
+@retval #LTTNG_CLEAR_HANDLE_STATUS_OK
+ Success: \lt_p{*result} is the result of the recording session
+ clearing operation identified by \lt_p{handle}.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
+ Unsatisfied precondition.
+@retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
+ Other error.
+
+@lt_pre_not_null{handle}
+@pre
+ You successfully waited for the completion of the recording session
+ clearing operation identified by \lt_p{handle} with
+ lttng_clear_handle_wait_for_completion().
+@lt_pre_not_null{result}
+
+@sa lttng_clear_handle_wait_for_completion() --
+ Waits for a recording session clearing operation to complete.
+*/
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