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