include/babeltrace2-ctf-writer/visitor.h

   1 #ifndef BABELTRACE2_CTF_WRITER_VISITOR_H
   2 #define BABELTRACE2_CTF_WRITER_VISITOR_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31 @defgroup ctfirvisitor CTF IR visitor
  32 @ingroup ctfir
  33 @brief CTF IR visitor.
  34
  35 @code
  36 #include <babeltrace2/trace-ir/visitor.h>
  37 @endcode
  38
  39 A CTF IR <strong><em>visitor</em></strong> is a function that you
  40 can use to visit the hierarchy of a
  41 \link ctfirtraceclass CTF IR trace class\endlink with
  42 bt_ctf_trace_visit() or of a
  43 \link ctfirstreamclass CTF IR stream class\endlink with
  44 bt_ctf_stream_class_visit().
  45
  46 The traversal of the object's hierarchy is always done in a
  47 pre-order fashion.
  48
  49 @sa ctfirstreamclass
  50 @sa ctfirtraceclass
  51
  52 @file
  53 @brief CTF IR visitor types and functions.
  54 @sa ctfirvisitor
  55
  56 @addtogroup ctfirvisitor
  57 @{
  58 */
  59
  60 /**
  61 @struct bt_ctf_object
  62 @brief A CTF IR object wrapper.
  63
  64 This structure wraps both a CTF IR object and its type
  65 (see #bt_ctf_object_type). It is used in the visiting function.
  66
  67 You can use the bt_ctf_object_get_type() and
  68 bt_ctf_object_get_object() accessors to get the type and wrapped
  69 CTF IR object of a CTF IR object wrapper.
  70
  71 A CTF IR object wrapper has <strong>no reference count</strong>: do \em
  72 not use bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
  73
  74 @sa ctfirvisitor
  75 */
  76 struct bt_ctf_visitor_object;
  77
  78 /**
  79 @brief  CTF IR object wrapper type.
  80 */
  81 enum bt_ctf_visitor_object_type {
  82         /// Unknown (used for errors).
  83         BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN = -1,
  84
  85         /// \ref ctfirtraceclass.
  86         BT_CTF_VISITOR_OBJECT_TYPE_TRACE = 0,
  87
  88         /// \ref ctfirstreamclass.
  89         BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1,
  90
  91         /// \ref ctfirstream.
  92         BT_CTF_VISITOR_OBJECT_TYPE_STREAM = 2,
  93
  94         /// \ref ctfireventclass.
  95         BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3,
  96
  97         /// \ref ctfirevent.
  98         BT_CTF_VISITOR_OBJECT_TYPE_EVENT = 4,
  99
 100         /// Number of entries in this enumeration.
 101         BT_CTF_VISITOR_OBJECT_TYPE_NR,
 102 };
 103
 104 /**
 105 @brief  Visting function type.
 106
 107 A function of this type is called by bt_ctf_trace_visit() or
 108 bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper
 109 \p object.
 110
 111 \p object has <strong>no reference count</strong>: do \em not use
 112 bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it.
 113
 114 @param[in] object       Currently visited CTF IR object wrapper.
 115 @param[in] data         User data.
 116 @returns                0 on success, or a negative value on error.
 117
 118 @prenotnull{object}
 119
 120 @sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class.
 121 @sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream
 122         class.
 123 */
 124 typedef int (*bt_ctf_visitor)(struct bt_ctf_visitor_object *object,
 125                 void *data);
 126
 127 /**
 128 @brief  Returns the type of the CTF IR object wrapped by the CTF IR
 129         object wrapper \p object.
 130
 131 @param[in] object       Object wrapper of which to get the type.
 132 @returns                Type of \p object.
 133
 134 @prenotnull{object}
 135
 136 @sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given
 137         CTF IR object wrapper.
 138 */
 139 enum bt_ctf_visitor_object_type bt_ctf_visitor_object_get_type(
 140                 struct bt_ctf_visitor_object *object);
 141
 142 /**
 143 @brief  Returns the CTF IR object wrapped by the CTF IR object
 144         wrapper \p object.
 145
 146 The reference count of \p object is \em not incremented by this
 147 function. On success, you must call bt_ctf_object_get_ref() on the return value to
 148 have your own reference.
 149
 150 @param[in] object       Object wrapper of which to get the wrapped
 151                         CTF IR object.
 152 @returns                CTF IR object wrapped by \p object.
 153
 154 @prenotnull{object}
 155 @post The reference count of the returned object is not modified.
 156
 157 @sa bt_ctf_visitor_object_get_type(): Returns the type of a given
 158         CTF IR object wrapper.
 159 */
 160 void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object *object);
 161
 162 /** @} */
 163
 164 #ifdef __cplusplus
 165 }
 166 #endif
 167
 168 #endif /* BABELTRACE2_CTF_WRITER_VISITOR_H */