include/babeltrace/ctf-writer/visitor.h

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