include/lttng/destruction-handle.h

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_DESTRUCTION_HANDLE_H
   9 #define LTTNG_DESTRUCTION_HANDLE_H
  10
  11 #include <lttng/lttng-error.h>
  12 #include <lttng/lttng-export.h>
  13 #include <lttng/rotation.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 /*!
  20 @addtogroup api_session_destr_handle
  21 @{
  22 */
  23
  24 /*!
  25 @struct lttng_destruction_handle
  26
  27 @brief
  28     Recording session destruction handle (opaque type).
  29 */
  30 struct lttng_destruction_handle;
  31
  32 /*!
  33 @brief
  34     Return type of recording session destruction handle fuctions.
  35
  36 Error status enumerators have a negative value.
  37 */
  38 enum lttng_destruction_handle_status {
  39         /// Success.
  40         LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
  41
  42         /// Recording session destruction operation completed.
  43         LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
  44
  45         /// Timeout reached.
  46         LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
  47
  48         /// Unsatisfied precondition.
  49         LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
  50
  51         /// Other error.
  52         LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
  53 };
  54
  55 /*!
  56 @brief
  57     Destroys the recording session destruction handle \lt_p{handle}.
  58
  59 @param[in] handle
  60     @parblock
  61     Recording session destruction handle to destroy.
  62
  63     May be \c NULL.
  64     @endparblock
  65 */
  66 LTTNG_EXPORT extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle *handle);
  67
  68 /*!
  69 @brief
  70     Waits for the recording session destruction operation identified by
  71     \lt_p{handle} to complete.
  72
  73 If this function returns #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED,
  74 then the recording session destruction operation identified by
  75 \lt_p{handle} completed. This doesn't mean, however, that the
  76 destruction operation itself succeeded; use
  77 lttng_destruction_handle_get_result() to know this.
  78
  79 @param[in] handle
  80     Recording session destruction handle which identifies the
  81     destruction operation of which to wait for completion.
  82 @param[in] timeout_ms
  83     Maximum time (milliseconds) to wait for the completion of the
  84     recording session destruction operation identified by \lt_p{handle}
  85     before returning #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT, or
  86     <code>-1</code> to wait indefinitely.
  87
  88 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED
  89     The recording session destruction operation identified by
  90     \lt_p{handle} completed (with or without success).
  91 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
  92     Unsatisfied precondition.
  93 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT
  94     The function waited for the completion of the recording session
  95     destruction operation for more than \lt_p{timeout_ms}&nbsp;ms.
  96 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
  97     Other error.
  98
  99 @lt_pre_not_null{handle}
 100
 101 @sa lttng_destruction_handle_get_result() --
 102     Returns whether or not a recording session destruction operation
 103     succeeded.
 104 */
 105 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 106 lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle *handle,
 107                                              int timeout_ms);
 108
 109 /*!
 110 @brief
 111     Sets \lt_p{*result} to the result of the recording session
 112     destruction operation identified by \lt_p{handle}.
 113
 114 You must successfully wait for the completion of the recording session
 115 destruction operation identified by \lt_p{handle} with
 116 lttng_destruction_handle_wait_for_completion() before you call this function.
 117
 118 On success, \lt_p{*result} is #LTTNG_OK if the destruction operation was
 119 successful.
 120
 121 @param[in] handle
 122     Handle of the recording session destruction operation of which to
 123     get the result.
 124 @param[out] result
 125     @parblock
 126     <strong>On success</strong>, this function sets \lt_p{*result} to
 127     the result of the recording session destruction operation identified
 128     by \lt_p{handle}.
 129
 130     \lt_p{*result} is #LTTNG_OK if the destruction operation was
 131     successful.
 132     @endparblock
 133
 134 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
 135     Success: \lt_p{*result} is the result of the recording session
 136     destruction operation identified by \lt_p{handle}.
 137 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
 138     Unsatisfied precondition.
 139 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
 140     Other error.
 141
 142 @lt_pre_not_null{handle}
 143 @pre
 144     You successfully waited for the completion of the recording session
 145     destruction operation identified by \lt_p{handle} with
 146     lttng_destruction_handle_wait_for_completion().
 147 @lt_pre_not_null{result}
 148
 149 @sa lttng_destruction_handle_wait_for_completion() --
 150     Waits for a recording session destruction operation to complete.
 151 */
 152 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 153 lttng_destruction_handle_get_result(const struct lttng_destruction_handle *handle,
 154                                     enum lttng_error_code *result);
 155
 156 /*!
 157 @brief
 158     Sets \lt_p{*rotation_state} to the state of a final
 159     \ref api_session_rotation "rotation" operation which the
 160     destruction of the recording session identified by \lt_p{handle}
 161     caused.
 162
 163 You must successfully wait for the completion of the recording session
 164 destruction operation identified by \lt_p{handle} with
 165 lttng_destruction_handle_wait_for_completion() before you call this
 166 function.
 167
 168 This function is only useful if LTTng performed at least one recording
 169 session rotation during the lifetime of the destroyed recording session.
 170
 171 @param[in] handle
 172     Handle of the destruction operation of the recording session of
 173     which to get the state of the final rotation operation.
 174 @param[out] rotation_state
 175     @parblock
 176     <strong>On success</strong>, this function sets
 177     \lt_p{*rotation_state} to the state of the final rotation operation
 178     which the recording session destruction operation identified by
 179     \lt_p{handle} caused.
 180
 181     \lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
 182     didn't perform any final recording session rotation.
 183     @endparblock
 184
 185 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
 186     Success: \lt_p{*rotation_state} is the state of the final rotation
 187     of the destroyed recording session.
 188 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
 189     Unsatisfied precondition.
 190 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
 191     Other error.
 192
 193 @lt_pre_not_null{handle}
 194 @pre
 195     You successfully waited for the completion of the recording session
 196     destruction operation identified by \lt_p{handle} with
 197     lttng_destruction_handle_wait_for_completion().
 198 @lt_pre_not_null{rotation_state}
 199
 200 @sa lttng_destruction_handle_get_archive_location() --
 201     Get the location of the trace chunk archive which a recording
 202     session destruction operation created.
 203 */
 204 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 205 lttng_destruction_handle_get_rotation_state(const struct lttng_destruction_handle *handle,
 206                                             enum lttng_rotation_state *rotation_state);
 207
 208 /*!
 209 @brief
 210     Sets \lt_p{*location} to the location of the final
 211     \ref api_session_rotation "trace chunk archive" which
 212     the destruction of the recording session identified by \lt_p{handle}
 213     created.
 214
 215 You must make sure that the destruction of the recording session caused
 216 a final, successful rotation with
 217 lttng_destruction_handle_get_rotation_state().
 218
 219 This function is only useful if LTTng performed at least one recording
 220 session rotation during the lifetime of the destroyed recording session.
 221
 222 @param[in] handle
 223     Handle of the destruction operation of the recording session of
 224     which to get the location of the final trace chunk archive.
 225 @param[out] location
 226     @parblock
 227     <strong>On success</strong>, this function sets
 228     \lt_p{*location} to the location of the final trace chunk archive
 229     which the recording session destruction operation identified by
 230     \lt_p{handle} created.
 231
 232     \lt_p{*location} is owned by \lt_p{handle}.
 233     @endparblock
 234
 235 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_OK
 236     Success: \lt_p{*location} is the location of the final trace
 237     chunk archive of the destroyed recording session.
 238 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
 239     Unsatisfied precondition.
 240 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
 241     Other error.
 242
 243 @lt_pre_not_null{handle}
 244 @pre
 245     lttng_destruction_handle_get_rotation_state() set the
 246     #LTTNG_ROTATION_STATE_COMPLETED state for \lt_p{handle}.
 247 @lt_pre_not_null{location}
 248
 249 @sa lttng_destruction_handle_get_rotation_state() --
 250     Get the state of the final rotation operation which a recording
 251     session destruction operation caused.
 252 */
 253 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 254 lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle,
 255                                               const struct lttng_trace_archive_location **location);
 256
 257 /// @}
 258
 259 #ifdef __cplusplus
 260 }
 261 #endif
 262
 263 #endif /* LTTNG_DESTRUCTION_HANDLE_H */