Interrupter

Detailed Description

Interrupter.

An interrupter is a simple object which has a single boolean state: set or not set.

You can use an interrupter to interrupt a running trace processing graph or query. The user and library functions periodically check if they are interrupted (with bt_self_component_sink_is_interrupted(), bt_self_message_iterator_is_interrupted(), or bt_query_executor_is_interrupted()); meanwhile, another thread or a signal handler sets the shared interrupter with bt_interrupter_set().

To interrupt a running trace processing graph or query:

1. Create an interrupter with bt_interrupter_create().

2. Before running a trace processing graph with bt_graph_run() or performing a query with bt_query_executor_query(), add the created interrupter to the object with bt_graph_add_interrupter() or bt_query_executor_add_interrupter().

   Alternatively, you can borrow the existing, default interrupter from those objects with bt_graph_borrow_default_interrupter() and bt_query_executor_borrow_default_interrupter().

3. Run the graph with bt_graph_run() or perform the query with bt_query_executor_query().
4. From a signal handler or another thread, call bt_interrupter_set() to set the shared interrupter.

Eventually, the trace processing graph or query thread checks if it's interrupted and stops processing, usually returning a status code which ends with _AGAIN.

You can add more than one interrupter to a trace processing graph and to a query executor. The bt_self_component_sink_is_interrupted(), bt_self_message_iterator_is_interrupted(), and bt_query_executor_is_interrupted() functions return the logical disjunction of all the added interrupters's states, so that any interrupter can interrupt the thread.

Once a trace processing graph or a query executor is interrupted and you get the thread's control back, you can reset the interrupter with bt_interrupter_reset() and continue the previous operation, calling bt_graph_run() or bt_query_executor_query() again.

An interrupter is a shared object: get a new reference with bt_interrupter_get_ref() and put an existing reference with bt_interrupter_put_ref().

The type of an interrupter is bt_interrupter.

Type
typedef struct bt_interrupter	bt_interrupter
	Interrupter.

Creation
bt_interrupter *	bt_interrupter_create (void)
	Creates a default interrupter. More...

State
void	bt_interrupter_set (bt_interrupter *interrupter)
	Sets the interrupter interrupter. More...
void	bt_interrupter_reset (bt_interrupter *interrupter)
	Resets the interrupter interrupter. More...
bt_bool	bt_interrupter_is_set (const bt_interrupter *interrupter)
	Returns whether or not the interrupter interrupter is set. More...

Reference count
void	bt_interrupter_get_ref (const bt_interrupter *interrupter)
	Increments the reference count of the interrupter interrupter. More...
void	bt_interrupter_put_ref (const bt_interrupter *interrupter)
	Decrements the reference count of the interrupter interrupter. More...
#define	BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)
	Decrements the reference count of the interrupter _interrupter, and then sets _interrupter to NULL. More...
#define	BT_INTERRUPTER_MOVE_REF(_dst, _src)
	Decrements the reference count of the interrupter _dst, sets _dst to _src, and then sets _src to NULL. More...

Macro Definition Documentation

BT_INTERRUPTER_PUT_REF_AND_RESET

#define BT_INTERRUPTER_PUT_REF_AND_RESET

(

_interrupter

)

Decrements the reference count of the interrupter _interrupter, and then sets _interrupter to NULL.

Parameters

_interrupter

Interrupter of which to decrement the reference count. Can contain NULL.

Precondition

_interrupter is an assignable expression.

BT_INTERRUPTER_MOVE_REF

#define BT_INTERRUPTER_MOVE_REF	(		_dst,
			_src
	)

Decrements the reference count of the interrupter _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves an interrupter reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

Function Documentation

bt_interrupter_create()

bt_interrupter* bt_interrupter_create

(

void

)

Creates a default interrupter.

On success, the returned interrupter is not set (bt_interrupter_is_set() returns BT_FALSE).

Returns

New interrupter reference, or NULL on memory error.

bt_interrupter_set()

void bt_interrupter_set

(

bt_interrupter *

interrupter

)

Sets the interrupter interrupter.

After you call this function, bt_interrupter_is_set() returns BT_TRUE.

Parameters

[in]

interrupter

Interrupter to set.

Precondition

interrupter is not NULL.

See also

bt_interrupter_reset() — Resets an interrupter.

bt_interrupter_is_set() — Returns whether or not an interrupter is set.

bt_interrupter_reset()

void bt_interrupter_reset

(

bt_interrupter *

interrupter

)

Resets the interrupter interrupter.

After you call this function, bt_interrupter_is_set() returns BT_FALSE.

Parameters

[in]

interrupter

Interrupter to reset.

Precondition

interrupter is not NULL.

See also

bt_interrupter_set() — Sets an interrupter.

bt_interrupter_is_set() — Returns whether or not an interrupter is set.

bt_interrupter_is_set()

bt_bool bt_interrupter_is_set

(

const bt_interrupter *

interrupter

)

Returns whether or not the interrupter interrupter is set.

Parameters

[in]

interrupter

Interrupter to reset.

Returns

BT_TRUE if interrupter is set.

Precondition

interrupter is not NULL.

See also

bt_interrupter_set() — Sets an interrupter.

bt_interrupter_reset() — Resets an interrupter.

bt_interrupter_get_ref()

void bt_interrupter_get_ref

(

const bt_interrupter *

interrupter

)

Increments the reference count of the interrupter interrupter.

Parameters

[in]

interrupter

Interrupter of which to increment the reference count. Can be NULL.

See also

bt_interrupter_put_ref() — Decrements the reference count of an interrupter.

bt_interrupter_put_ref()

void bt_interrupter_put_ref

(

const bt_interrupter *

interrupter

)

Decrements the reference count of the interrupter interrupter.

Parameters

[in]

interrupter

Interrupter of which to decrement the reference count. Can be NULL.

See also

bt_interrupter_get_ref() — Increments the reference count of an interrupter.