include/babeltrace2-ctf-writer/stream.h

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