include/lttng/clear-handle.h

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  * Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-only
   6  *
   7  */
   8
   9 #ifndef LTTNG_CLEAR_HANDLE_H
  10 #define LTTNG_CLEAR_HANDLE_H
  11
  12 #include <lttng/lttng-error.h>
  13 #include <lttng/lttng-export.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 /*!
  20 @addtogroup api_session_clear
  21 @{
  22 */
  23
  24 /*!
  25 @struct lttng_clear_handle
  26
  27 @brief
  28     \lt_obj_c_session clearing handle (opaque type).
  29 */
  30 struct lttng_clear_handle;
  31
  32 /*!
  33 @brief
  34     Return type of \lt_obj_session clearing handle functions.
  35
  36 Error status enumerators have a negative value.
  37 */
  38 enum lttng_clear_handle_status {
  39         /// Success.
  40         LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
  41
  42         /// Recording session clearing operation completed.
  43         LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
  44
  45         /// Timeout reached.
  46         LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
  47
  48         /// Unsatisfied precondition.
  49         LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
  50
  51         /// Other error.
  52         LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
  53 };
  54
  55 /*!
  56 @brief
  57     Destroys the \lt_obj_session clearing handle \lt_p{handle}.
  58
  59 @param[in] handle
  60     @parblock
  61     Recording session clearing handle to destroy.
  62
  63     May be \c NULL.
  64     @endparblock
  65 */
  66 LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);
  67
  68 /*!
  69 @brief
  70     Waits for the \lt_obj_session clearing operation identified by
  71     \lt_p{handle} to complete.
  72
  73 If this function returns #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED, then the
  74 recording session clearing operation identified by \lt_p{handle}
  75 completed. This doesn't mean, however, that the clearing operation
  76 itself succeeded; use lttng_clear_handle_get_result() to know this.
  77
  78 @param[in] handle
  79     Recording session clearing handle which identifies the clearing
  80     operation of which to wait for completion.
  81 @param[in] timeout_ms
  82     Maximum time (milliseconds) to wait for the completion of the
  83     recording session clearing operation identified by \lt_p{handle}
  84     before returning #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT, or
  85     <code>-1</code> to wait indefinitely.
  86
  87 @retval #LTTNG_CLEAR_HANDLE_STATUS_COMPLETED
  88     The recording session clearing operation identified by \lt_p{handle}
  89     completed (with or without success).
  90 @retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
  91     Unsatisfied precondition.
  92 @retval #LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT
  93     The function waited for the completion of the recording session
  94     clearing operation for more than \lt_p{timeout_ms}&nbsp;ms.
  95 @retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
  96     Other error.
  97
  98 @lt_pre_not_null{handle}
  99
 100 @sa lttng_clear_handle_get_result() --
 101     Returns whether or not a recording session clearing operation
 102     succeeded.
 103 */
 104 LTTNG_EXPORT extern enum lttng_clear_handle_status
 105 lttng_clear_handle_wait_for_completion(struct lttng_clear_handle *handle, int timeout_ms);
 106
 107 /*!
 108 @brief
 109     Sets \lt_p{*result} to the result of the \lt_obj_session clearing
 110     operation identified by \lt_p{handle}.
 111
 112 You must successfully wait for the completion of the recording session
 113 clearing operation identified by \lt_p{handle} with
 114 lttng_clear_handle_wait_for_completion() before you call this function.
 115
 116 On success, \lt_p{*result} is #LTTNG_OK if the clearing operation was
 117 successful.
 118
 119 @param[in] handle
 120     Handle of the recording session clearing operation of which to get
 121     the result.
 122 @param[out] result
 123     @parblock
 124     <strong>On success</strong>, this function sets \lt_p{*result} to
 125     the result of the recording session clearing operation identified by
 126     \lt_p{handle}.
 127
 128     \lt_p{*result} is #LTTNG_OK if the clearing operation was
 129     successful.
 130     @endparblock
 131
 132 @retval #LTTNG_CLEAR_HANDLE_STATUS_OK
 133     Success: \lt_p{*result} is the result of the recording session
 134     clearing operation identified by \lt_p{handle}.
 135 @retval #LTTNG_CLEAR_HANDLE_STATUS_INVALID
 136     Unsatisfied precondition.
 137 @retval #LTTNG_CLEAR_HANDLE_STATUS_ERROR
 138     Other error.
 139
 140 @lt_pre_not_null{handle}
 141 @pre
 142     You successfully waited for the completion of the recording session
 143     clearing operation identified by \lt_p{handle} with
 144     lttng_clear_handle_wait_for_completion().
 145 @lt_pre_not_null{result}
 146
 147 @sa lttng_clear_handle_wait_for_completion() --
 148     Waits for a recording session clearing operation to complete.
 149 */
 150 LTTNG_EXPORT extern enum lttng_clear_handle_status
 151 lttng_clear_handle_get_result(const struct lttng_clear_handle *handle,
 152                               enum lttng_error_code *result);
 153
 154 /// @}
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif /* LTTNG_CLEAR_HANDLE_H */