Commit | Line | Data |
---|---|---|
f2c1f0d4 | 1 | /* |
ab5be9fa MJ |
2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
3 | * Copyright (C) 2019 Mathieu Desnoyers <mathieu.desnoyers@efficios.com> | |
f2c1f0d4 | 4 | * |
ab5be9fa | 5 | * SPDX-License-Identifier: LGPL-2.1-only |
f2c1f0d4 | 6 | * |
f2c1f0d4 MD |
7 | */ |
8 | ||
9 | #ifndef LTTNG_CLEAR_HANDLE_H | |
10 | #define LTTNG_CLEAR_HANDLE_H | |
11 | ||
12 | #include <lttng/lttng-error.h> | |
4bd69c5f | 13 | #include <lttng/lttng-export.h> |
f2c1f0d4 MD |
14 | |
15 | #ifdef __cplusplus | |
16 | extern "C" { | |
17 | #endif | |
18 | ||
048f01ef PP |
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 | */ | |
f2c1f0d4 MD |
30 | struct lttng_clear_handle; |
31 | ||
048f01ef PP |
32 | /*! |
33 | @brief | |
34 | Return type of \lt_obj_session clearing handle functions. | |
35 | ||
36 | Error status enumerators have a negative value. | |
37 | */ | |
f2c1f0d4 | 38 | enum lttng_clear_handle_status { |
048f01ef | 39 | /// Success. |
f2c1f0d4 | 40 | LTTNG_CLEAR_HANDLE_STATUS_OK = 0, |
048f01ef PP |
41 | |
42 | /// Recording session clearing operation completed. | |
f2c1f0d4 | 43 | LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1, |
048f01ef PP |
44 | |
45 | /// Timeout reached. | |
f2c1f0d4 | 46 | LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2, |
048f01ef PP |
47 | |
48 | /// Unsatisfied precondition. | |
49 | LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1, | |
50 | ||
51 | /// Other error. | |
52 | LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2, | |
f2c1f0d4 MD |
53 | }; |
54 | ||
048f01ef PP |
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 | */ | |
4bd69c5f | 66 | LTTNG_EXPORT extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle); |
f2c1f0d4 | 67 | |
048f01ef PP |
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} 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 | */ | |
4bd69c5f | 104 | LTTNG_EXPORT extern enum lttng_clear_handle_status |
28f23191 | 105 | lttng_clear_handle_wait_for_completion(struct lttng_clear_handle *handle, int timeout_ms); |
f2c1f0d4 | 106 | |
048f01ef PP |
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 | */ | |
4bd69c5f | 150 | LTTNG_EXPORT extern enum lttng_clear_handle_status |
28f23191 JG |
151 | lttng_clear_handle_get_result(const struct lttng_clear_handle *handle, |
152 | enum lttng_error_code *result); | |
048f01ef PP |
153 | |
154 | /// @} | |
155 | ||
316f62af JR |
156 | #ifdef __cplusplus |
157 | } | |
158 | #endif | |
f2c1f0d4 MD |
159 | |
160 | #endif /* LTTNG_CLEAR_HANDLE_H */ |