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're 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:

Create an interrupter with bt_interrupter_create().
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().
Run the graph with bt_graph_run() or perform the query with bt_query_executor_query().
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 the states of all the added interrupters, so that any interrupter can interrupt the thread.

Once a trace processing graph or a query executor is interrupted and you get back the control of the thread, 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.

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

State
void	bt_interrupter_set (bt_interrupter *interrupter)
	Sets the interrupter interrupter.

void	bt_interrupter_reset (bt_interrupter *interrupter)
	Resets the interrupter interrupter.

bt_bool	bt_interrupter_is_set (const bt_interrupter *interrupter)
	Returns whether or not the interrupter interrupter is set.

Reference count
void	bt_interrupter_get_ref (const bt_interrupter *interrupter)
	Increments the reference count of the interrupter interrupter.

void	bt_interrupter_put_ref (const bt_interrupter *interrupter)
	Decrements the reference count of the interrupter interrupter.

#define	BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter)
	Decrements the reference count of the interrupter _interrupter, and then sets _interrupter to `NULL`.

#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`.

Type
typedef struct bt_interrupter	bt_interrupter
	Interrupter.

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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.

Detailed Description

Creation

State

Reference count

Type

Macro Definition Documentation

◆ BT_INTERRUPTER_PUT_REF_AND_RESET

◆ BT_INTERRUPTER_MOVE_REF

Function Documentation

◆ bt_interrupter_create()

◆ bt_interrupter_set()

◆ bt_interrupter_reset()

◆ bt_interrupter_is_set()

◆ bt_interrupter_get_ref()

◆ bt_interrupter_put_ref()