include/babeltrace2-ctf-writer/stream.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_STREAM_H
   8 #define BABELTRACE2_CTF_WRITER_STREAM_H
   9
  10 #include <stdint.h>
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 struct bt_ctf_stream;
  17 struct bt_ctf_event;
  18
  19 /*
  20  * bt_ctf_stream_get_discarded_events_count: get the number of discarded
  21  * events associated with this stream.
  22  *
  23  * Note that discarded events are not stored if the stream's packet
  24  * context has no "events_discarded" field. An error will be returned
  25  * in that case.
  26  *
  27  * @param stream Stream instance.
  28  *
  29  * Returns the number of discarded events, a negative value on error.
  30  */
  31 extern int bt_ctf_stream_get_discarded_events_count(
  32                 struct bt_ctf_stream *stream, uint64_t *count);
  33
  34 /*
  35  * bt_ctf_stream_append_discarded_events: increment discarded events count.
  36  *
  37  * Increase the current packet's discarded event count. Has no effect if the
  38  * stream class' packet context has no "events_discarded" field.
  39  *
  40  * @param stream Stream instance.
  41  * @param event_count Number of discarded events to add to the stream's current
  42  *      packet.
  43  */
  44 extern void bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream,
  45                 uint64_t event_count);
  46
  47 /*
  48  * bt_ctf_stream_append_event: append an event to the stream.
  49  *
  50  * Append "event" to the stream's current packet. The stream's associated clock
  51  * will be sampled during this call. The event shall not be modified after
  52  * being appended to a stream. The stream will share the event's ownership by
  53  * incrementing its reference count. The current packet is not flushed to disk
  54  * until the next call to bt_ctf_stream_flush.
  55  *
  56  * The stream event context will be sampled for every appended event if
  57  * a stream event context was defined.
  58  *
  59  * @param stream Stream instance.
  60  * @param event Event instance to append to the stream's current packet.
  61  *
  62  * Returns 0 on success, a negative value on error.
  63  */
  64 extern int bt_ctf_stream_append_event(struct bt_ctf_stream *stream,
  65                 struct bt_ctf_event *event);
  66
  67 /*
  68  * bt_ctf_stream_get_packet_header: get a stream's packet header.
  69  *
  70  * @param stream Stream instance.
  71  *
  72  * Returns a field instance on success, NULL on error.
  73  */
  74 extern struct bt_ctf_field *bt_ctf_stream_get_packet_header(
  75                 struct bt_ctf_stream *stream);
  76
  77 /*
  78  * bt_ctf_stream_set_packet_header: set a stream's packet header.
  79  *
  80  * The packet header's type must match the trace's packet header
  81  * type.
  82  *
  83  * @param stream Stream instance.
  84  * @param packet_header Packet header instance.
  85  *
  86  * Returns a field instance on success, NULL on error.
  87  */
  88 extern int bt_ctf_stream_set_packet_header(
  89                 struct bt_ctf_stream *stream,
  90                 struct bt_ctf_field *packet_header);
  91
  92 /*
  93  * bt_ctf_stream_get_packet_context: get a stream's packet context.
  94  *
  95  * @param stream Stream instance.
  96  *
  97  * Returns a field instance on success, NULL on error.
  98  */
  99 extern struct bt_ctf_field *bt_ctf_stream_get_packet_context(
 100                 struct bt_ctf_stream *stream);
 101
 102 /*
 103  * bt_ctf_stream_set_packet_context: set a stream's packet context.
 104  *
 105  * The packet context's type must match the stream class' packet
 106  * context type.
 107  *
 108  * @param stream Stream instance.
 109  * @param packet_context Packet context field instance.
 110  *
 111  * Returns a field instance on success, NULL on error.
 112  */
 113 extern int bt_ctf_stream_set_packet_context(
 114                 struct bt_ctf_stream *stream,
 115                 struct bt_ctf_field *packet_context);
 116
 117 /*
 118  * bt_ctf_stream_flush: flush a stream.
 119  *
 120  * The stream's current packet's events will be flushed, thus closing the
 121  * current packet. Events subsequently appended to the stream will be
 122  * added to a new packet.
 123  *
 124  * Flushing will also set the packet context's default attributes if
 125  * they remained unset while populating the current packet. These default
 126  * attributes, along with their expected types, are detailed in stream-class.h.
 127  *
 128  * @param stream Stream instance.
 129  *
 130  * Returns 0 on success, a negative value on error.
 131  */
 132 extern int bt_ctf_stream_flush(struct bt_ctf_stream *stream);
 133
 134 extern int bt_ctf_stream_is_writer(struct bt_ctf_stream *stream);
 135
 136 extern
 137 struct bt_ctf_stream *bt_ctf_stream_create(
 138                 struct bt_ctf_stream_class *stream_class,
 139                 const char *name, uint64_t id);
 140
 141 extern struct bt_ctf_stream_class *bt_ctf_stream_get_class(
 142                 struct bt_ctf_stream *stream);
 143
 144 extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream);
 145
 146 extern int64_t bt_ctf_stream_get_id(struct bt_ctf_stream *stream);
 147
 148 /* Pre-2.0 CTF writer compatibility */
 149 static inline
 150 void bt_ctf_stream_get(struct bt_ctf_stream *stream)
 151 {
 152         bt_ctf_object_get_ref(stream);
 153 }
 154
 155 /* Pre-2.0 CTF writer compatibility */
 156 static inline
 157 void bt_ctf_stream_put(struct bt_ctf_stream *stream)
 158 {
 159         bt_ctf_object_put_ref(stream);
 160 }
 161
 162 #ifdef __cplusplus
 163 }
 164 #endif
 165
 166 #endif /* BABELTRACE2_CTF_WRITER_STREAM_H */