2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_DESTRUCTION_HANDLE_H
9 #define LTTNG_DESTRUCTION_HANDLE_H
11 #include <lttng/lttng-error.h>
12 #include <lttng/lttng-export.h>
13 #include <lttng/rotation.h>
20 @addtogroup api_session_destr_handle
25 @struct lttng_destruction_handle
28 Recording session destruction handle (opaque type).
30 struct lttng_destruction_handle
;
34 Return type of recording session destruction handle fuctions.
36 Error status enumerators have a negative value.
38 enum lttng_destruction_handle_status
{
40 LTTNG_DESTRUCTION_HANDLE_STATUS_OK
= 0,
42 /// Recording session destruction operation completed.
43 LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED
= 1,
46 LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT
= 2,
48 /// Unsatisfied precondition.
49 LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID
= -1,
52 LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
= -2,
57 Destroys the recording session destruction handle \lt_p{handle}.
61 Recording session destruction handle to destroy.
66 LTTNG_EXPORT
extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle
*handle
);
70 Waits for the recording session destruction operation identified by
71 \lt_p{handle} to complete.
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.
80 Recording session destruction handle which identifies the
81 destruction operation of which to wait for completion.
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.
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} ms.
96 @retval #LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR
99 @lt_pre_not_null{handle}
101 @sa lttng_destruction_handle_get_result() --
102 Returns whether or not a recording session destruction operation
105 LTTNG_EXPORT
extern enum lttng_destruction_handle_status
106 lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle
*handle
,
111 Sets \lt_p{*result} to the result of the recording session
112 destruction operation identified by \lt_p{handle}.
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.
118 On success, \lt_p{*result} is #LTTNG_OK if the destruction operation was
122 Handle of the recording session destruction operation of which to
126 <strong>On success</strong>, this function sets \lt_p{*result} to
127 the result of the recording session destruction operation identified
130 \lt_p{*result} is #LTTNG_OK if the destruction operation was
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
142 @lt_pre_not_null{handle}
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}
149 @sa lttng_destruction_handle_wait_for_completion() --
150 Waits for a recording session destruction operation to complete.
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
);
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}
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
168 This function is only useful if LTTng performed at least one recording
169 session rotation during the lifetime of the destroyed recording session.
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
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.
181 \lt_p{*rotation_state} is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng
182 didn't perform any final recording session rotation.
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
193 @lt_pre_not_null{handle}
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}
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.
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
);
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}
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().
219 This function is only useful if LTTng performed at least one recording
220 session rotation during the lifetime of the destroyed recording session.
223 Handle of the destruction operation of the recording session of
224 which to get the location of the final trace chunk archive.
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.
232 \lt_p{*location} is owned by \lt_p{handle}.
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
243 @lt_pre_not_null{handle}
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}
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.
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
);
263 #endif /* LTTNG_DESTRUCTION_HANDLE_H */