X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=include%2Flttng%2Fclear-handle.h;h=9a8048456421e5b7a62f2097e887094bcde82a13;hb=HEAD;hp=ea9edd456cc7f47849afb41d81560eec1c7e05fe;hpb=f2c1f0d46e0ed64f57a4f3bc3a5d6c5b6d743b77;p=lttng-tools.git diff --git a/include/lttng/clear-handle.h b/include/lttng/clear-handle.h index ea9edd456..9a8048456 100644 --- a/include/lttng/clear-handle.h +++ b/include/lttng/clear-handle.h @@ -1,89 +1,160 @@ /* - * Copyright (C) 2019 - Jérémie Galarneau - * Copyright (C) 2019 - Mathieu Desnoyers + * Copyright (C) 2019 Jérémie Galarneau + * Copyright (C) 2019 Mathieu Desnoyers * - * 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. + * SPDX-License-Identifier: LGPL-2.1-only * - * 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 +#include #ifdef __cplusplus 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. - */ -extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle); +/*! +@brief + Destroys the \lt_obj_session clearing handle \lt_p{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); +@param[in] handle + @parblock + Recording session clearing handle to destroy. -/* - * 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); + May be \c NULL. + @endparblock +*/ +LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle); + +/*! +@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); + +/*! +@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 #endif /* LTTNG_CLEAR_HANDLE_H */