[babeltrace.git] / include / babeltrace / context.h

#ifndef _BABELTRACE_CONTEXT_H
#define _BABELTRACE_CONTEXT_H

/*
 * BabelTrace
 *
 * context header
 *
 * Copyright 2012 EfficiOS Inc. and Linux Foundation
 *
 * Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 *         Julien Desfossez <julien.desfossez@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.
 */

struct trace_collection;

/*
 * The context represents the object in which a trace_collection is open. As
 * long as this structure is allocated, the trace_collection is open and the
 * traces it contains can be read and seeked by the iterators and callbacks.
 *
 * It has to be created with the bt_context_create() function and destroyed by
 * bt_context_destroy()
 */
struct bt_context {
	struct trace_collection *tc;
	int refcount;
	int last_trace_handle_id;
};

/*
 * bt_context_create : create a Babeltrace context
 *
 * Allocate a new context and assign the trace_collection passed in
 * parameter as the context trace_collection. The trace_collection
 * must contain an array of valid trace_descriptors. The creation of
 * the context sets the refcount to 1.
 *
 * Returns an allocated context on success and NULL on error
 */
struct bt_context *bt_context_create(struct trace_collection *tc);

/*
 * bt_context_destroy : destroy a context
 *
 * If the context is still in use (by an iterator or a callback), the
 * destroy fails and returns -1, on success : return 0.
 */
int bt_context_destroy(struct bt_context *ctx);

/*
 * bt_context_get and bt_context_put : increments and decrement the refcount of
 * the context
 *
 * These functions ensures that the context won't be destroyed when it is in
 * use. The same number of get and put has to be done to be able to destroy a
 * context.
 *
 * Return 0 on success, -1 if the context pointer is invalid.  When the context
 * refcount is decremented to 0 by a bt_context_put, it calls
 * bt_context_destroy to free the context. In this case the return code of
 * bt_context_destroy is returned.
 */
int bt_context_get(struct bt_context *ctx);
int bt_context_put(struct bt_context *ctx);

#endif /* _BABELTRACE_CONTEXT_H */
Commit	Line	Data
	1	#ifndef _BABELTRACE_CONTEXT_H
	2	#define _BABELTRACE_CONTEXT_H
	3
	4	/*
	5	* BabelTrace
	6	*
	7	* context header
	8	*
	9	* Copyright 2012 EfficiOS Inc. and Linux Foundation
	10	*
	11	* Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
	12	* Julien Desfossez <julien.desfossez@efficios.com>
	13	*
	14	* Permission is hereby granted, free of charge, to any person obtaining a copy
	15	* of this software and associated documentation files (the "Software"), to deal
	16	* in the Software without restriction, including without limitation the rights
	17	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	18	* copies of the Software, and to permit persons to whom the Software is
	19	* furnished to do so, subject to the following conditions:
	20	*
	21	* The above copyright notice and this permission notice shall be included in
	22	* all copies or substantial portions of the Software.
	23	*/
	24
	25	struct trace_collection;
	26
	27	/*
	28	* The context represents the object in which a trace_collection is open. As
	29	* long as this structure is allocated, the trace_collection is open and the
	30	* traces it contains can be read and seeked by the iterators and callbacks.
	31	*
	32	* It has to be created with the bt_context_create() function and destroyed by
	33	* bt_context_destroy()
	34	*/
	35	struct bt_context {
	36	struct trace_collection *tc;
	37	int refcount;
	38	int last_trace_handle_id;
	39	};
	40
	41	/*
	42	* bt_context_create : create a Babeltrace context
	43	*
	44	* Allocate a new context and assign the trace_collection passed in
	45	* parameter as the context trace_collection. The trace_collection
	46	* must contain an array of valid trace_descriptors. The creation of
	47	* the context sets the refcount to 1.
	48	*
	49	* Returns an allocated context on success and NULL on error
	50	*/
	51	struct bt_context bt_context_create(struct trace_collection tc);
	52
	53	/*
	54	* bt_context_destroy : destroy a context
	55	*
	56	* If the context is still in use (by an iterator or a callback), the
	57	* destroy fails and returns -1, on success : return 0.
	58	*/
	59	int bt_context_destroy(struct bt_context *ctx);
	60
	61	/*
	62	* bt_context_get and bt_context_put : increments and decrement the refcount of
	63	* the context
	64	*
	65	* These functions ensures that the context won't be destroyed when it is in
	66	* use. The same number of get and put has to be done to be able to destroy a
	67	* context.
	68	*
	69	* Return 0 on success, -1 if the context pointer is invalid. When the context
	70	* refcount is decremented to 0 by a bt_context_put, it calls
	71	* bt_context_destroy to free the context. In this case the return code of
	72	* bt_context_destroy is returned.
	73	*/
	74	int bt_context_get(struct bt_context *ctx);
	75	int bt_context_put(struct bt_context *ctx);
	76
	77	#endif /* _BABELTRACE_CONTEXT_H */