X-Git-Url: https://git.liburcu.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fdestruction-handle.h;fp=include%2Flttng%2Fdestruction-handle.h;h=108ba4aa6bd35f8681e07536e9aafb81ba08d19a;hp=d14bc16a883b0ad743ecb9fdc5b0c4015d7d25cc;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b diff --git a/include/lttng/destruction-handle.h b/include/lttng/destruction-handle.h index d14bc16a8..108ba4aa6 100644 --- a/include/lttng/destruction-handle.h +++ b/include/lttng/destruction-handle.h @@ -16,123 +16,246 @@ extern "C" { #endif -/* - * Handle used to represent a specific instance of session destruction - * operation. - * - * See lttng_destroy_session_ext() in lttng/session.h. - */ +/*! +@addtogroup api_session_destr_handle +@{ +*/ + +/*! +@struct lttng_destruction_handle + +@brief + Recording session destruction handle (opaque type). +*/ struct lttng_destruction_handle; -/* - * Negative values indicate errors. Values >= 0 indicate success. - */ +/*! +@brief + Return type of recording session destruction handle fuctions. + +Error status enumerators have a negative value. +*/ enum lttng_destruction_handle_status { - /* Generic error. */ - LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2, - /* Invalid parameters provided */ - LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1, - /* Success. */ + /// Success. LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0, - /* Destruction operation completed successfully. */ + + /// Recording session destruction operation completed. LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1, - /* Operation timed out. */ + + /// Timeout reached. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2, + + /// Unsatisfied precondition. + LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1, + + /// Other error. + LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2, }; -/* - * Destroy an lttng_destruction_session handle. - * The handle should be discarded after this call. - */ +/*! +@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); -/* - * Wait for the destruction of a session to complete. - * - * A negative timeout_ms value can be used to wait indefinitely. - * - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED if the session destruction - * operation was completed. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT is returned - * to indicate that the wait timed out. - * On error, one of the negative lttng_destruction_handle_status is returned. - * - * Note: This function returning a success status does not mean that - * the destruction operation itself succeeded; it indicates that the _wait_ - * operation completed successfully. - */ +/*! +@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 + -1 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} 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); -/* - * Get the result of a session destruction operation. - * - * This function must be used on a session destruction handle which was - * successfully waited on. - * - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the result of the session - * destruction operation could be obtained. Check the value of 'result' to - * determine if the destruction of the session completed successfully or not. - * - * On error, one of the negative lttng_destruction_handle_status is returned. - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction - * 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 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 + On success, 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); -/* - * Get the status of the session rotation performed as part of the session's - * destruction. - * - * A session will perform a final rotation if it was ever rotated over its - * lifetime. If this happens, this function returns the state of the rotation - * that was performed. - * - * This function must be used on a session destruction handle which was - * successfully waited on. - * - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session - * rotation could be obtained. Check the value of 'rotation_state' to - * determine if the rotation of the session completed successfully or not. - * - * On error, one of the negative lttng_destruction_handle_status is returned. - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction - * was not waited-on using the handle or if the arguments of the function are - * invalid (e.g. NULL). - * - * Note that if no rotation was performed, rotation_state will be set to - * LTTNG_ROTATION_STATE_NO_ROTATION. - */ +/*! +@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 + On success, 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); -/* - * Get the location of the archive resulting from the rotation performed during - * the session's destruction. - * - * This function must be used on a session destruction handle which was - * successfully waited on and a session rotation must have been be completed - * successfully in order for this call to succeed. - * - * The location returned remains owned by the session destruction handle. - * - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the location of the archive - * resulting from the session rotation could be obtained. - * - * On error, one of the negative lttng_destruction_handle_status is returned. - * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction - * was not waited-on using the handle, if no session rotation occurred as part - * of the session's destruction, or if the arguments of the function are - * invalid (e.g. NULL). - */ +/*! +@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 + On success, 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