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
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 /*
  19  * Handle used to represent a specific instance of session clear
  20  * operation.
  21  */
  22 struct lttng_clear_handle;
  23
  24 /*
  25  * Negative values indicate errors. Values >= 0 indicate success.
  26  */
  27 enum lttng_clear_handle_status {
  28         LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
  29         LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
  30         LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
  31         LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
  32         LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
  33 };
  34
  35 /*
  36  * Destroy an lttng_clear_handle.
  37  * The handle should be discarded after this call.
  38  */
  39 extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);
  40
  41 /*
  42  * Wait for a session clear operation to complete.
  43  *
  44  * A negative timeout_ms value can be used to wait indefinitely.
  45  *
  46  * Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
  47  * operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
  48  * to indicate that the wait timed out.
  49  * On error, one of the negative lttng_clear_handle_status is returned.
  50  *
  51  * Note: This function returning a success status does not mean that
  52  * the clear operation itself succeeded; it indicates that the _wait_
  53  * operation completed successfully.
  54  */
  55 extern enum lttng_clear_handle_status
  56         lttng_clear_handle_wait_for_completion(
  57                 struct lttng_clear_handle *handle, int timeout_ms);
  58
  59 /*
  60  * Get the result of a session clear operation.
  61  *
  62  * This function must be used on a clear handle which was successfully waited
  63  * on.
  64  *
  65  * Returns LTTNG_CLEAR_HANDLE_STATUS_OK if the result of the session
  66  * clear operation could be obtained. Check the value of 'result' to
  67  * determine if the session clear operation completed successfully or not.
  68  *
  69  * On error, one of the negative lttng_clear_handle_status is returned.
  70  * Returns LTTNG_CLEAR_HANDLE_STATUS_INVALID if the clear operation
  71  * was not waited-on using the handle or if the arguments of the function are
  72  * invalid (e.g. NULL).
  73  */
  74 extern enum lttng_clear_handle_status
  75         lttng_clear_handle_get_result(
  76                 const struct lttng_clear_handle *handle,
  77                 enum lttng_error_code *result);
  78
  79 #endif /* LTTNG_CLEAR_HANDLE_H */