include/babeltrace2-ctf-writer/visitor.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_CTF_WRITER_VISITOR_H
   8 #define BABELTRACE2_CTF_WRITER_VISITOR_H
   9
  10 #ifdef __cplusplus
  11 extern "C" {
  12 #endif
  13
  14 /**
  15 @defgroup ctfirvisitor CTF IR visitor
  16 @ingroup ctfir
  17 @brief CTF IR visitor.
  18
  19 @code
  20 #include <babeltrace2/trace-ir/visitor.h>
  21 @endcode
  22
  23 A CTF IR <strong><em>visitor</em></strong> is a function that you
  24 can use to visit the hierarchy of a
  25 \link ctfirtraceclass CTF IR trace class\endlink with
  26 bt_ctf_trace_visit() or of a
  27 \link ctfirstreamclass CTF IR stream class\endlink with
  28 bt_ctf_stream_class_visit().
  29
  30 The traversal of the object's hierarchy is always done in a
  31 pre-order fashion.
  32
  33 @sa ctfirstreamclass
  34 @sa ctfirtraceclass
  35
  36 @file
  37 @brief CTF IR visitor types and functions.
  38 @sa ctfirvisitor
  39
  40 @addtogroup ctfirvisitor
  41 @{
  42 */
  43
  44 /**
  45 @struct bt_ctf_object
  46 @brief A CTF IR object wrapper.
  47
  48 This structure wraps both a CTF IR object and its type
  49 (see #bt_ctf_object_type). It is used in the visiting function.
  50
  51 You can use the bt_ctf_object_get_type() and
  52 bt_ctf_object_get_object() accessors to get the type and wrapped
  53 CTF IR object of a CTF IR object wrapper.
  54
  55 A CTF IR object wrapper has <strong>no reference count</strong>: do \em
  56 not use bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
  57
  58 @sa ctfirvisitor
  59 */
  60 struct bt_ctf_visitor_object;
  61
  62 /**
  63 @brief  CTF IR object wrapper type.
  64 */
  65 enum bt_ctf_visitor_object_type {
  66         /// Unknown (used for errors).
  67         BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN = -1,
  68
  69         /// \ref ctfirtraceclass.
  70         BT_CTF_VISITOR_OBJECT_TYPE_TRACE = 0,
  71
  72         /// \ref ctfirstreamclass.
  73         BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1,
  74
  75         /// \ref ctfirstream.
  76         BT_CTF_VISITOR_OBJECT_TYPE_STREAM = 2,
  77
  78         /// \ref ctfireventclass.
  79         BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3,
  80
  81         /// \ref ctfirevent.
  82         BT_CTF_VISITOR_OBJECT_TYPE_EVENT = 4,
  83
  84         /// Number of entries in this enumeration.
  85         BT_CTF_VISITOR_OBJECT_TYPE_NR,
  86 };
  87
  88 /**
  89 @brief  Visting function type.
  90
  91 A function of this type is called by bt_ctf_trace_visit() or
  92 bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper
  93 \p object.
  94
  95 \p object has <strong>no reference count</strong>: do \em not use
  96 bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
  97
  98 @param[in] object       Currently visited CTF IR object wrapper.
  99 @param[in] data         User data.
 100 @returns                0 on success, or a negative value on error.
 101
 102 @prenotnull{object}
 103
 104 @sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class.
 105 @sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream
 106         class.
 107 */
 108 typedef int (*bt_ctf_visitor)(struct bt_ctf_visitor_object *object,
 109                 void *data);
 110
 111 /**
 112 @brief  Returns the type of the CTF IR object wrapped by the CTF IR
 113         object wrapper \p object.
 114
 115 @param[in] object       Object wrapper of which to get the type.
 116 @returns                Type of \p object.
 117
 118 @prenotnull{object}
 119
 120 @sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given
 121         CTF IR object wrapper.
 122 */
 123 enum bt_ctf_visitor_object_type bt_ctf_visitor_object_get_type(
 124                 struct bt_ctf_visitor_object *object);
 125
 126 /**
 127 @brief  Returns the CTF IR object wrapped by the CTF IR object
 128         wrapper \p object.
 129
 130 The reference count of \p object is \em not incremented by this
 131 function. On success, you must call bt_ctf_object_get_ref() on the return value to
 132 have your own reference.
 133
 134 @param[in] object       Object wrapper of which to get the wrapped
 135                         CTF IR object.
 136 @returns                CTF IR object wrapped by \p object.
 137
 138 @prenotnull{object}
 139 @post The reference count of the returned object is not modified.
 140
 141 @sa bt_ctf_visitor_object_get_type(): Returns the type of a given
 142         CTF IR object wrapper.
 143 */
 144 void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object *object);
 145
 146 /** @} */
 147
 148 #ifdef __cplusplus
 149 }
 150 #endif
 151
 152 #endif /* BABELTRACE2_CTF_WRITER_VISITOR_H */