include/babeltrace2-ctf-writer/writer.h

   1 #ifndef BABELTRACE2_CTF_WRITER_WRITER_H
   2 #define BABELTRACE2_CTF_WRITER_WRITER_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 #include <babeltrace2-ctf-writer/field-types.h>
  27 #include <babeltrace2-ctf-writer/stream-class.h>
  28 #include <babeltrace2-ctf-writer/stream.h>
  29 #include <babeltrace2-ctf-writer/trace.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 struct bt_ctf_writer;
  36 struct bt_ctf_stream;
  37 struct bt_ctf_stream_class;
  38 struct bt_ctf_clock;
  39
  40 /*
  41  * bt_ctf_writer_create: create a writer instance.
  42  *
  43  * Allocate a new writer that will produce a trace in the given path.
  44  * The creation of a writer sets its reference count to 1.
  45  *
  46  * @param path Path to the trace's containing folder (string is copied).
  47  *
  48  * Returns an allocated writer on success, NULL on error.
  49  */
  50 extern struct bt_ctf_writer *bt_ctf_writer_create(const char *path);
  51
  52 /*
  53  * bt_ctf_writer_get_trace: Get a writer's associated trace.
  54  *
  55  * @param writer Writer instance.
  56  *
  57  * Return the writer's associated instance, NULL on error.
  58  */
  59 extern struct bt_ctf_trace *bt_ctf_writer_get_trace(
  60                 struct bt_ctf_writer *writer);
  61
  62 /*
  63  * bt_ctf_writer_create_stream: create a stream instance.
  64  *
  65  * Allocate a new stream instance and register it to the writer. The creation of
  66  * a stream sets its reference count to 1.
  67  *
  68  * @param writer Writer instance.
  69  * @param stream_class Stream class to instantiate.
  70  *
  71  * Returns an allocated stream on success, NULL on error.
  72  */
  73 extern struct bt_ctf_stream *bt_ctf_writer_create_stream(
  74                 struct bt_ctf_writer *writer,
  75                 struct bt_ctf_stream_class *stream_class);
  76
  77 /*
  78  * bt_ctf_writer_add_environment_field: add an environment field to the trace.
  79  *
  80  * Add an environment field to the trace. The name and value parameters are
  81  * copied.
  82  *
  83  * @param writer Writer instance.
  84  * @param name Name of the environment field (will be copied).
  85  * @param value Value of the environment field (will be copied).
  86  *
  87  * Returns 0 on success, a negative value on error.
  88  */
  89 extern int bt_ctf_writer_add_environment_field(struct bt_ctf_writer *writer,
  90                 const char *name,
  91                 const char *value);
  92
  93 /*
  94  * bt_ctf_writer_add_environment_field_int64: add an environment field to the trace.
  95  *
  96  * Add an environment field to the trace. The name and value parameters are
  97  * copied.
  98  *
  99  * @param writer Writer instance.
 100  * @param name Name of the environment field (will be copied).
 101  * @param value Value of the environment field.
 102  *
 103  * Returns 0 on success, a negative value on error.
 104  */
 105 extern int bt_ctf_writer_add_environment_field_int64(
 106                 struct bt_ctf_writer *writer,
 107                 const char *name,
 108                 int64_t value);
 109
 110 /*
 111  * bt_ctf_writer_add_clock: add a clock to the trace.
 112  *
 113  * Add a clock to the trace. Clocks assigned to stream classes must be
 114  * registered to the writer.
 115  *
 116  * @param writer Writer instance.
 117  * @param clock Clock to add to the trace.
 118  *
 119  * Returns 0 on success, a negative value on error.
 120  */
 121 extern int bt_ctf_writer_add_clock(struct bt_ctf_writer *writer,
 122                 struct bt_ctf_clock *clock);
 123
 124 /*
 125  * bt_ctf_writer_get_metadata_string: get meta-data string.
 126  *
 127  * Get the trace's TSDL meta-data. The caller assumes the ownership of the
 128  * returned string.
 129  *
 130  * @param writer Writer instance.
 131  *
 132  * Returns the metadata string on success, NULL on error.
 133  */
 134 extern char *bt_ctf_writer_get_metadata_string(struct bt_ctf_writer *writer);
 135
 136 /*
 137  * bt_ctf_writer_flush_metadata: flush the trace's metadata to disk.
 138  *
 139  * Flush the trace's metadata to the metadata file. Note that the metadata will
 140  * be flushed automatically when the Writer instance is released (last call to
 141  * bt_ctf_writer_put).
 142  *
 143  * @param writer Writer instance.
 144  */
 145 extern void bt_ctf_writer_flush_metadata(struct bt_ctf_writer *writer);
 146
 147 /*
 148  * bt_ctf_writer_set_byte_order: set a field type's byte order.
 149  *
 150  * Set the trace's byte order. Defaults to the host machine's endianness.
 151  *
 152  * @param writer Writer instance.
 153  * @param byte_order Trace's byte order.
 154  *
 155  * Returns 0 on success, a negative value on error.
 156  *
 157  * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
 158  * to the CTF specification, is defined as "the byte order described in the
 159  * trace description".
 160  */
 161 extern int bt_ctf_writer_set_byte_order(struct bt_ctf_writer *writer,
 162                 enum bt_ctf_byte_order byte_order);
 163
 164 /*
 165  * bt_ctf_writer_get and bt_ctf_writer_put: increment and decrement the
 166  * writer's reference count.
 167  *
 168  * You may also use bt_ctf_get() and bt_ctf_put() with writer objects.
 169  *
 170  * These functions ensure that the writer won't be destroyed while it
 171  * is in use. The same number of get and put (plus one extra put to
 172  * release the initial reference done at creation) have to be done to
 173  * destroy a writer.
 174  *
 175  * When the writer's reference count is decremented to 0 by a
 176  * bt_ctf_writer_put, the writer is freed.
 177  *
 178  * @param writer Writer instance.
 179  */
 180
 181 /* Pre-2.0 CTF writer compatibility */
 182 static inline
 183 void bt_ctf_writer_get(struct bt_ctf_writer *writer)
 184 {
 185         bt_ctf_object_get_ref(writer);
 186 }
 187
 188 /* Pre-2.0 CTF writer compatibility */
 189 static inline
 190 void bt_ctf_writer_put(struct bt_ctf_writer *writer)
 191 {
 192         bt_ctf_object_put_ref(writer);
 193 }
 194
 195 #ifdef __cplusplus
 196 }
 197 #endif
 198
 199 #endif /* BABELTRACE2_CTF_WRITER_WRITER_H */