[lttngtop.git] / lib / babeltrace / ctf-writer / writer.h

#ifndef BABELTRACE_CTF_WRITER_WRITER_H
#define BABELTRACE_CTF_WRITER_WRITER_H

/*
 * BabelTrace - CTF Writer: Writer
 *
 * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * The Common Trace Format (CTF) Specification is available at
 * http://www.efficios.com/ctf
 */

#include <babeltrace/ctf-ir/event-types.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_ctf_writer;
struct bt_ctf_stream;
struct bt_ctf_stream_class;
struct bt_ctf_clock;

/*
 * bt_ctf_writer_create: create a writer instance.
 *
 * Allocate a new writer that will produce a trace in the given path.
 * The creation of a writer sets its reference count to 1.
 *
 * @param path Path to the trace's containing folder (string is copied).
 *
 * Returns an allocated writer on success, NULL on error.
 */
extern struct bt_ctf_writer *bt_ctf_writer_create(const char *path);

/*
 * bt_ctf_writer_create_stream: create a stream instance.
 *
 * Allocate a new stream instance and register it to the writer. The creation of
 * a stream sets its reference count to 1.
 *
 * @param writer Writer instance.
 * @param stream_class Stream class to instantiate.
 *
 * Returns an allocated writer on success, NULL on error.
 */
extern struct bt_ctf_stream *bt_ctf_writer_create_stream(
		struct bt_ctf_writer *writer,
		struct bt_ctf_stream_class *stream_class);

/*
 * bt_ctf_writer_add_environment_field: add an environment field to the trace.
 *
 * Add an environment field to the trace. The name and value parameters are
 * copied.
 *
 * @param writer Writer instance.
 * @param name Name of the environment field (will be copied).
 * @param value Value of the environment field (will be copied).
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_writer_add_environment_field(struct bt_ctf_writer *writer,
		const char *name,
		const char *value);

/*
 * bt_ctf_writer_add_clock: add a clock to the trace.
 *
 * Add a clock to the trace. Clocks assigned to stream classes must be
 * registered to the writer.
 *
 * @param writer Writer instance.
 * @param clock Clock to add to the trace.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_writer_add_clock(struct bt_ctf_writer *writer,
		struct bt_ctf_clock *clock);

/*
 * bt_ctf_writer_get_metadata_string: get meta-data string.
 *
 * Get the trace's TSDL meta-data. The caller assumes the ownership of the
 * returned string.
 *
 * @param writer Writer instance.
 *
 * Returns the metadata string on success, NULL on error.
 */
extern char *bt_ctf_writer_get_metadata_string(struct bt_ctf_writer *writer);

/*
 * bt_ctf_writer_flush_metadata: flush the trace's metadata to disk.
 *
 * Flush the trace's metadata to the metadata file. Note that the metadata will
 * be flushed automatically when the Writer instance is released (last call to
 * bt_ctf_writer_put).
 *
 * @param writer Writer instance.
 */
extern void bt_ctf_writer_flush_metadata(struct bt_ctf_writer *writer);

/*
 * bt_ctf_writer_set_byte_order: set a field type's byte order.
 *
 * Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE,
 * the host machine's endianness.
 *
 * @param writer Writer instance.
 * @param byte_order Trace's byte order.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_writer_set_byte_order(struct bt_ctf_writer *writer,
		enum bt_ctf_byte_order byte_order);

/*
 * bt_ctf_writer_get and bt_ctf_writer_put: increment and decrement the
 * writer's reference count.
 *
 * These functions ensure that the writer 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 writer.
 *
 * When the writer's reference count is decremented to 0 by a
 * bt_ctf_writer_put, the writer is freed.
 *
 * @param writer Writer instance.
 */
extern void bt_ctf_writer_get(struct bt_ctf_writer *writer);
extern void bt_ctf_writer_put(struct bt_ctf_writer *writer);

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_WRITER_WRITER_H */
Commit	Line	Data
12a91e9d JD	1	#ifndef BABELTRACE_CTF_WRITER_WRITER_H
	2	#define BABELTRACE_CTF_WRITER_WRITER_H
	3
	4	/*
	5	* BabelTrace - CTF Writer: Writer
	6	*
4a325d7e	7	* Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
12a91e9d JD	8	*
	9	* Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
	10	*
	11	* Permission is hereby granted, free of charge, to any person obtaining a copy
	12	* of this software and associated documentation files (the "Software"), to deal
	13	* in the Software without restriction, including without limitation the rights
	14	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	15	* copies of the Software, and to permit persons to whom the Software is
	16	* furnished to do so, subject to the following conditions:
	17	*
	18	* The above copyright notice and this permission notice shall be included in
	19	* all copies or substantial portions of the Software.
	20	*
	21	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	22	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	23	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	24	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	25	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	26	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	27	* SOFTWARE.
	28	*
	29	* The Common Trace Format (CTF) Specification is available at
	30	* http://www.efficios.com/ctf
	31	*/
	32
4a325d7e JD	33	#include <babeltrace/ctf-ir/event-types.h>
4a325d7e JD	34
12a91e9d JD	35	#ifdef __cplusplus
	36	extern "C" {
	37	#endif
	38
	39	struct bt_ctf_writer;
	40	struct bt_ctf_stream;
	41	struct bt_ctf_stream_class;
	42	struct bt_ctf_clock;
	43
12a91e9d JD	44	/*
	45	* bt_ctf_writer_create: create a writer instance.
	46	*
	47	* Allocate a new writer that will produce a trace in the given path.
	48	* The creation of a writer sets its reference count to 1.
	49	*
	50	* @param path Path to the trace's containing folder (string is copied).
	51	*
	52	* Returns an allocated writer on success, NULL on error.
	53	*/
	54	extern struct bt_ctf_writer bt_ctf_writer_create(const char path);
	55
	56	/*
	57	* bt_ctf_writer_create_stream: create a stream instance.
	58	*
	59	* Allocate a new stream instance and register it to the writer. The creation of
	60	* a stream sets its reference count to 1.
	61	*
	62	* @param writer Writer instance.
	63	* @param stream_class Stream class to instantiate.
	64	*
	65	* Returns an allocated writer on success, NULL on error.
	66	*/
	67	extern struct bt_ctf_stream *bt_ctf_writer_create_stream(
	68	struct bt_ctf_writer *writer,
	69	struct bt_ctf_stream_class *stream_class);
	70
	71	/*
	72	* bt_ctf_writer_add_environment_field: add an environment field to the trace.
	73	*
	74	* Add an environment field to the trace. The name and value parameters are
	75	* copied.
	76	*
	77	* @param writer Writer instance.
	78	* @param name Name of the environment field (will be copied).
	79	* @param value Value of the environment field (will be copied).
	80	*
	81	* Returns 0 on success, a negative value on error.
	82	*/
	83	extern int bt_ctf_writer_add_environment_field(struct bt_ctf_writer *writer,
	84	const char *name,
	85	const char *value);
	86
	87	/*
	88	* bt_ctf_writer_add_clock: add a clock to the trace.
	89	*
	90	* Add a clock to the trace. Clocks assigned to stream classes must be
	91	* registered to the writer.
	92	*
	93	* @param writer Writer instance.
	94	* @param clock Clock to add to the trace.
	95	*
	96	* Returns 0 on success, a negative value on error.
	97	*/
	98	extern int bt_ctf_writer_add_clock(struct bt_ctf_writer *writer,
	99	struct bt_ctf_clock *clock);
	100
	101	/*
	102	* bt_ctf_writer_get_metadata_string: get meta-data string.
	103	*
	104	* Get the trace's TSDL meta-data. The caller assumes the ownership of the
	105	* returned string.
	106	*
	107	* @param writer Writer instance.
108	*
109	* Returns the metadata string on success, NULL on error.
110	*/
111	extern char bt_ctf_writer_get_metadata_string(struct bt_ctf_writer writer);
112
113	/*
114	* bt_ctf_writer_flush_metadata: flush the trace's metadata to disk.
115	*
116	* Flush the trace's metadata to the metadata file. Note that the metadata will
117	* be flushed automatically when the Writer instance is released (last call to
118	* bt_ctf_writer_put).
119	*
120	* @param writer Writer instance.
121	*/
122	extern void bt_ctf_writer_flush_metadata(struct bt_ctf_writer *writer);
123
124	/*
125	* bt_ctf_writer_set_byte_order: set a field type's byte order.
126	*
127	* Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE,
128	* the host machine's endianness.
129	*
130	* @param writer Writer instance.
131	* @param byte_order Trace's byte order.
132	*
133	* Returns 0 on success, a negative value on error.
134	*/
135	extern int bt_ctf_writer_set_byte_order(struct bt_ctf_writer *writer,
136	enum bt_ctf_byte_order byte_order);
137
138	/*
139	* bt_ctf_writer_get and bt_ctf_writer_put: increment and decrement the
140	* writer's reference count.
141	*
142	* These functions ensure that the writer won't be destroyed while it
143	* is in use. The same number of get and put (plus one extra put to
144	* release the initial reference done at creation) have to be done to
145	* destroy a writer.
146	*
147	* When the writer's reference count is decremented to 0 by a
148	* bt_ctf_writer_put, the writer is freed.
149	*
150	* @param writer Writer instance.
151	*/
152	extern void bt_ctf_writer_get(struct bt_ctf_writer *writer);
153	extern void bt_ctf_writer_put(struct bt_ctf_writer *writer);
154
155	#ifdef __cplusplus
156	}
157	#endif
158
159	#endif /* BABELTRACE_CTF_WRITER_WRITER_H */