Commit | Line | Data |
---|---|---|
3e3665b8 | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
3e3665b8 | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
3e3665b8 | 5 | * |
3e3665b8 JG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_DESTRUCTION_HANDLE_H | |
9 | #define LTTNG_DESTRUCTION_HANDLE_H | |
10 | ||
3e3665b8 | 11 | #include <lttng/lttng-error.h> |
4bd69c5f | 12 | #include <lttng/lttng-export.h> |
28f23191 | 13 | #include <lttng/rotation.h> |
3e3665b8 JG |
14 | |
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | ||
048f01ef PP |
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 | */ | |
3e3665b8 JG |
30 | struct lttng_destruction_handle; |
31 | ||
048f01ef PP |
32 | /*! |
33 | @brief | |
34 | Return type of recording session destruction handle fuctions. | |
35 | ||
36 | Error status enumerators have a negative value. | |
37 | */ | |
3e3665b8 | 38 | enum lttng_destruction_handle_status { |
048f01ef | 39 | /// Success. |
3e3665b8 | 40 | LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0, |
048f01ef PP |
41 | |
42 | /// Recording session destruction operation completed. | |
3e3665b8 | 43 | LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1, |
048f01ef PP |
44 | |
45 | /// Timeout reached. | |
3e3665b8 | 46 | LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2, |
048f01ef PP |
47 | |
48 | /// Unsatisfied precondition. | |
49 | LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1, | |
50 | ||
51 | /// Other error. | |
52 | LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2, | |
3e3665b8 JG |
53 | }; |
54 | ||
048f01ef PP |
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 | */ | |
28f23191 | 66 | LTTNG_EXPORT extern void lttng_destruction_handle_destroy(struct lttng_destruction_handle *handle); |
3e3665b8 | 67 | |
048f01ef PP |
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} 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 | */ | |
4bd69c5f | 105 | LTTNG_EXPORT extern enum lttng_destruction_handle_status |
28f23191 JG |
106 | lttng_destruction_handle_wait_for_completion(struct lttng_destruction_handle *handle, |
107 | int timeout_ms); | |
3e3665b8 | 108 | |
048f01ef PP |
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 | */ | |
4bd69c5f | 152 | LTTNG_EXPORT extern enum lttng_destruction_handle_status |
28f23191 JG |
153 | lttng_destruction_handle_get_result(const struct lttng_destruction_handle *handle, |
154 | enum lttng_error_code *result); | |
3e3665b8 | 155 | |
048f01ef PP |
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 | */ | |
4bd69c5f | 204 | LTTNG_EXPORT extern enum lttng_destruction_handle_status |
28f23191 JG |
205 | lttng_destruction_handle_get_rotation_state(const struct lttng_destruction_handle *handle, |
206 | enum lttng_rotation_state *rotation_state); | |
3e3665b8 | 207 | |
048f01ef PP |
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 | */ | |
4bd69c5f | 253 | LTTNG_EXPORT extern enum lttng_destruction_handle_status |
28f23191 JG |
254 | lttng_destruction_handle_get_archive_location(const struct lttng_destruction_handle *handle, |
255 | const struct lttng_trace_archive_location **location); | |
3e3665b8 | 256 | |
048f01ef PP |
257 | /// @} |
258 | ||
4da7eebd JG |
259 | #ifdef __cplusplus |
260 | } | |
261 | #endif | |
262 | ||
3e3665b8 | 263 | #endif /* LTTNG_DESTRUCTION_HANDLE_H */ |