include/lttng/destruction-handle.h

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_DESTRUCTION_HANDLE_H
   9 #define LTTNG_DESTRUCTION_HANDLE_H
  10
  11 #include <lttng/rotation.h>
  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 destruction
  21  * operation.
  22  *
  23  * See lttng_destroy_session_ext() in lttng/session.h.
  24  */
  25 struct lttng_destruction_handle;
  26
  27 /*
  28  * Negative values indicate errors. Values >= 0 indicate success.
  29  */
  30 enum lttng_destruction_handle_status {
  31         /* Generic error. */
  32         LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
  33         /* Invalid parameters provided */
  34         LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
  35         /* Success. */
  36         LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
  37         /* Destruction operation completed successfully. */
  38         LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
  39         /* Operation timed out. */
  40         LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
  41 };
  42
  43 /*
  44  * Destroy an lttng_destruction_session handle.
  45  * The handle should be discarded after this call.
  46  */
  47 LTTNG_EXPORT extern void lttng_destruction_handle_destroy(
  48                 struct lttng_destruction_handle *handle);
  49
  50 /*
  51  * Wait for the destruction of a session to complete.
  52  *
  53  * A negative timeout_ms value can be used to wait indefinitely.
  54  *
  55  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED if the session destruction
  56  * operation was completed. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT is returned
  57  * to indicate that the wait timed out.
  58  * On error, one of the negative lttng_destruction_handle_status is returned.
  59  *
  60  * Note: This function returning a success status does not mean that
  61  * the destruction operation itself succeeded; it indicates that the _wait_
  62  * operation completed successfully.
  63  */
  64 LTTNG_EXPORT extern enum lttng_destruction_handle_status
  65 lttng_destruction_handle_wait_for_completion(
  66                 struct lttng_destruction_handle *handle, int timeout_ms);
  67
  68 /*
  69  * Get the result of a session destruction operation.
  70  *
  71  * This function must be used on a session destruction handle which was
  72  * successfully waited on.
  73  *
  74  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the result of the session
  75  * destruction operation could be obtained. Check the value of 'result' to
  76  * determine if the destruction of the session completed successfully or not.
  77  *
  78  * On error, one of the negative lttng_destruction_handle_status is returned.
  79  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
  80  * was not waited-on using the handle or if the arguments of the function are
  81  * invalid (e.g. NULL).
  82  */
  83 LTTNG_EXPORT extern enum lttng_destruction_handle_status
  84 lttng_destruction_handle_get_result(
  85                 const struct lttng_destruction_handle *handle,
  86                 enum lttng_error_code *result);
  87
  88 /*
  89  * Get the status of the session rotation performed as part of the session's
  90  * destruction.
  91  *
  92  * A session will perform a final rotation if it was ever rotated over its
  93  * lifetime. If this happens, this function returns the state of the rotation
  94  * that was performed.
  95  *
  96  * This function must be used on a session destruction handle which was
  97  * successfully waited on.
  98  *
  99  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session
 100  * rotation could be obtained. Check the value of 'rotation_state' to
 101  * determine if the rotation of the session completed successfully or not.
 102  *
 103  * On error, one of the negative lttng_destruction_handle_status is returned.
 104  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
 105  * was not waited-on using the handle or if the arguments of the function are
 106  * invalid (e.g. NULL).
 107  *
 108  * Note that if no rotation was performed, rotation_state will be set to
 109  * LTTNG_ROTATION_STATE_NO_ROTATION.
 110  */
 111 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 112 lttng_destruction_handle_get_rotation_state(
 113                 const struct lttng_destruction_handle *handle,
 114                 enum lttng_rotation_state *rotation_state);
 115
 116 /*
 117  * Get the location of the archive resulting from the rotation performed during
 118  * the session's destruction.
 119  *
 120  * This function must be used on a session destruction handle which was
 121  * successfully waited on and a session rotation must have been be completed
 122  * successfully in order for this call to succeed.
 123  *
 124  * The location returned remains owned by the session destruction handle.
 125  *
 126  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the location of the archive
 127  * resulting from the session rotation could be obtained.
 128  *
 129  * On error, one of the negative lttng_destruction_handle_status is returned.
 130  * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
 131  * was not waited-on using the handle, if no session rotation occurred as part
 132  * of the session's destruction, or if the arguments of the function are
 133  * invalid (e.g. NULL).
 134  */
 135 LTTNG_EXPORT extern enum lttng_destruction_handle_status
 136 lttng_destruction_handle_get_archive_location(
 137                 const struct lttng_destruction_handle *handle,
 138                 const struct lttng_trace_archive_location **location);
 139
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144 #endif /* LTTNG_DESTRUCTION_HANDLE_H */