X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-writer%2Fstream.h;h=bc368f4e435ea73e84873adeb54620600c8fb61f;hb=98bd6ec2cbc37814f9d92372fd8e9aa2c5956489;hp=d5f2f7e257ca3a8a62296598d3017e41c26517b2;hpb=cf6f1e34ddc261f0e469fab8b4c087319b0a7ad2;p=babeltrace.git diff --git a/include/babeltrace/ctf-writer/stream.h b/include/babeltrace/ctf-writer/stream.h index d5f2f7e2..bc368f4e 100644 --- a/include/babeltrace/ctf-writer/stream.h +++ b/include/babeltrace/ctf-writer/stream.h @@ -2,9 +2,7 @@ #define BABELTRACE_CTF_WRITER_STREAM_H /* - * BabelTrace - CTF Writer: Stream - * - * Copyright 2013 EfficiOS Inc. + * Copyright 2013, 2014 Jérémie Galarneau * * Author: Jérémie Galarneau * @@ -30,19 +28,35 @@ * http://www.efficios.com/ctf */ -#include +#include #ifdef __cplusplus extern "C" { #endif -struct bt_ctf_event; struct bt_ctf_stream; +struct bt_ctf_event; + +/* + * bt_ctf_stream_get_discarded_events_count: get the number of discarded + * events associated with this stream. + * + * Note that discarded events are not stored if the stream's packet + * context has no "events_discarded" field. An error will be returned + * in that case. + * + * @param stream Stream instance. + * + * Returns the number of discarded events, a negative value on error. + */ +extern int bt_ctf_stream_get_discarded_events_count( + struct bt_ctf_stream *stream, uint64_t *count); /* * bt_ctf_stream_append_discarded_events: increment discarded events count. * - * Increase the current packet's discarded event count. + * Increase the current packet's discarded event count. Has no effect if the + * stream class' packet context has no "events_discarded" field. * * @param stream Stream instance. * @param event_count Number of discarded events to add to the stream's current @@ -60,6 +74,9 @@ extern void bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream, * incrementing its reference count. The current packet is not flushed to disk * until the next call to bt_ctf_stream_flush. * + * The stream event context will be sampled for every appended event if + * a stream event context was defined. + * * @param stream Stream instance. * @param event Event instance to append to the stream's current packet. * @@ -69,33 +86,99 @@ extern int bt_ctf_stream_append_event(struct bt_ctf_stream *stream, struct bt_ctf_event *event); /* - * bt_ctf_stream_flush: flush a stream. + * bt_ctf_stream_get_packet_header: get a stream's packet header. * - * The stream's current packet's events will be flushed to disk. Events - * subsequently appended to the stream will be added to a new packet. + * @param stream Stream instance. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_stream_get_packet_header( + struct bt_ctf_stream *stream); + +/* + * bt_ctf_stream_set_packet_header: set a stream's packet header. + * + * The packet header's type must match the trace's packet header + * type. * * @param stream Stream instance. + * @param packet_header Packet header instance. * - * Returns 0 on success, a negative value on error. + * Returns a field instance on success, NULL on error. */ -extern int bt_ctf_stream_flush(struct bt_ctf_stream *stream); +extern int bt_ctf_stream_set_packet_header( + struct bt_ctf_stream *stream, + struct bt_ctf_field *packet_header); + +/* + * bt_ctf_stream_get_packet_context: get a stream's packet context. + * + * @param stream Stream instance. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_stream_get_packet_context( + struct bt_ctf_stream *stream); + +/* + * bt_ctf_stream_set_packet_context: set a stream's packet context. + * + * The packet context's type must match the stream class' packet + * context type. + * + * @param stream Stream instance. + * @param packet_context Packet context field instance. + * + * Returns a field instance on success, NULL on error. + */ +extern int bt_ctf_stream_set_packet_context( + struct bt_ctf_stream *stream, + struct bt_ctf_field *packet_context); /* - * bt_ctf_stream_get and bt_ctf_stream_put: increment and decrement the - * stream's reference count. + * bt_ctf_stream_flush: flush a stream. * - * These functions ensure that the stream won't be destroyed while it - * is in use. The same number of get and put (plus one extra put to - * release the initial reference done at creation) have to be done to - * destroy a stream. + * The stream's current packet's events will be flushed, thus closing the + * current packet. Events subsequently appended to the stream will be + * added to a new packet. * - * When the stream's reference count is decremented to 0 by a - * bt_ctf_stream_put, the stream is freed. + * Flushing will also set the packet context's default attributes if + * they remained unset while populating the current packet. These default + * attributes, along with their expected types, are detailed in stream-class.h. * * @param stream Stream instance. + * + * Returns 0 on success, a negative value on error. */ -extern void bt_ctf_stream_get(struct bt_ctf_stream *stream); -extern void bt_ctf_stream_put(struct bt_ctf_stream *stream); +extern int bt_ctf_stream_flush(struct bt_ctf_stream *stream); + +extern int bt_ctf_stream_is_writer(struct bt_ctf_stream *stream); + +extern +struct bt_ctf_stream *bt_ctf_stream_create( + struct bt_ctf_stream_class *stream_class, + const char *name, uint64_t id); + +extern struct bt_ctf_stream_class *bt_ctf_stream_get_class( + struct bt_ctf_stream *stream); + +extern const char *bt_ctf_stream_get_name(struct bt_ctf_stream *stream); + +extern int64_t bt_ctf_stream_get_id(struct bt_ctf_stream *stream); + +/* Pre-2.0 CTF writer compatibility */ +static inline +void bt_ctf_stream_get(struct bt_ctf_stream *stream) +{ + bt_ctf_object_get_ref(stream); +} + +/* Pre-2.0 CTF writer compatibility */ +static inline +void bt_ctf_stream_put(struct bt_ctf_stream *stream) +{ + bt_ctf_object_put_ref(stream); +} #ifdef __cplusplus }