Detailed Description

Executor of component class object queries.

A query executor is an executor of component class object queries.

A component class can implement a query method to offer one or more objects depending on the query parameters.

Both the query parameters and the returned objects are values.

The query operation feature exists so that you can get benefit from a component class's implementation to get information about a trace, a stream, a distant server, and so on. For example, the source.ctf.lttng-live component class (see babeltrace2-source.ctf.lttng-live(7)) offers the sessions object to list the available LTTng live tracing session names and other properties.

The semantics of the query parameters and the returned object are completely defined by the component class implementation: the library does not enforce or suggest any layout. The best way to know which objects you can query from a component class, what are the expected and optional parameters, and what the returned object contains is to read this component class's documentation.

The purpose of the query executor itself is to keep some state for a specific query operation. For example, you can set a query executor's logging level with bt_query_executor_set_logging_level(); then a component class's query method can get the executor's current logging level with bt_query_executor_get_logging_level().

Also, the query executor is an interruptible object: a long or blocking query operation can run, checking whether the executor is interrupted periodically, while another thread or a signal handler can interrupt the executor.

A query executor is a shared object: get a new reference with bt_query_executor_get_ref() and put an existing reference with bt_query_executor_put_ref().

The type of a query executor is bt_query_executor.

Create a query executor with bt_query_executor_create() or bt_query_executor_create_with_method_data(). When you do so, you set the name of the object to query, from which component class to query the object, and what are the query parameters. You cannot change those properties once the query executor is created. With bt_query_executor_create_with_method_data(), you can also pass a custom, void * pointer to the component class's query method.

Perform a query operation with bt_query_executor_query(). This function can return BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, in which case you can try to perform a query operation again later. It can also return BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, which means the component class does not offer the requested object.

To interrupt a running query operation, either:

Borrow the query executor's default interrupter with bt_query_executor_borrow_default_interrupter() and set it with bt_interrupter_set().

When you call bt_query_executor_create() or bt_query_executor_create_with_method_data(), the returned query executor has a default interrupter.
Add your own interrupter with bt_query_executor_add_interrupter() before you perform the query operation with bt_query_executor_query().

Then, set the interrupter with bt_interrupter_set().

Property

A query executor has the following property:

Logging level

Logging level of the query executor's query operations.

Use bt_query_executor_set_logging_level() and bt_query_executor_get_logging_level().

Type
typedef struct bt_query_executor	bt_query_executor
	Query executor.

Creation
bt_query_executor *	bt_query_executor_create (const bt_component_class component_class, const char object_name, const bt_value *params)
	Alias of bt_query_executor_create_with_method_data() with the method_data parameter set to `NULL`.

bt_query_executor *	bt_query_executor_create_with_method_data (const bt_component_class component_class, const char object_name, const bt_value params, void method_data)
	Creates a query executor to query the object named object_name from the component class component_class with the parameters params and the query user data method_data. More...

Query operation
enum	bt_query_executor_query_status { BT_QUERY_EXECUTOR_QUERY_STATUS_OK, BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR, BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR }
	Status codes for bt_query_executor_query(). More...

typedef enum bt_query_executor_query_status	bt_query_executor_query_status
	Status codes for bt_query_executor_query().

bt_query_executor_query_status	bt_query_executor_query (bt_query_executor query_executor, const bt_value *result)
	Performs a query operation using the query executor query_executor, setting *result to the operation's result on success. More...

Property
enum	bt_query_executor_set_logging_level_status { BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK }
	Status codes for bt_query_executor_set_logging_level(). More...

typedef enum bt_query_executor_set_logging_level_status	bt_query_executor_set_logging_level_status
	Status codes for bt_query_executor_set_logging_level().

bt_query_executor_set_logging_level_status	bt_query_executor_set_logging_level (bt_query_executor *query_executor, bt_logging_level logging_level)
	Sets the logging level of the query executor query_executor to logging_level. More...

bt_logging_level	bt_query_executor_get_logging_level (const bt_query_executor *query_executor)
	Returns the logging level of the query executor query_executor. More...

Interruption
enum	bt_query_executor_add_interrupter_status { BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK, BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR }
	Status codes for bt_query_executor_add_interrupter(). More...

typedef enum bt_query_executor_add_interrupter_status	bt_query_executor_add_interrupter_status
	Status codes for bt_query_executor_add_interrupter().

bt_query_executor_add_interrupter_status	bt_query_executor_add_interrupter (bt_query_executor query_executor, const bt_interrupter interrupter)
	Adds the interrupter interrupter to the query executor query_executor. More...

bt_interrupter *	bt_query_executor_borrow_default_interrupter (bt_query_executor *query_executor)
	Borrows the default interrupter from the query executor query_executor. More...

bt_bool	bt_query_executor_is_interrupted (const bt_query_executor *query_executor)
	Returns whether or not the query executor query_executor is interrupted, that is, whether or not any of its interrupters, including its default interrupter, is set. More...

Reference count
void	bt_query_executor_get_ref (const bt_query_executor *query_executor)
	Increments the reference count of the query executor query_executor. More...

void	bt_query_executor_put_ref (const bt_query_executor *query_executor)
	Decrements the reference count of the query executor query_executor. More...

#define	BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor)
	Decrements the reference count of the query executor _query_executor, and then sets _query_executor to `NULL`. More...

#define	BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src)
	Decrements the reference count of the query executor _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Enumeration Type Documentation

◆ bt_query_executor_query_status

enum bt_query_executor_query_status

Status codes for bt_query_executor_query().

Enumerator
BT_QUERY_EXECUTOR_QUERY_STATUS_OK	Success.
BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT	Unknown object to query.
BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN	Try again.
BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR	Out of memory.
BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR	Other error.

◆ bt_query_executor_set_logging_level_status

enum bt_query_executor_set_logging_level_status

Status codes for bt_query_executor_set_logging_level().

Enumerator
BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK	Success.

◆ bt_query_executor_add_interrupter_status

enum bt_query_executor_add_interrupter_status

Status codes for bt_query_executor_add_interrupter().

Enumerator
BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK	Success.
BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	Out of memory.

Macro Definition Documentation

◆ BT_QUERY_EXECUTOR_PUT_REF_AND_RESET

#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET ( _query_executor )

Decrements the reference count of the query executor _query_executor, and then sets _query_executor to NULL.

Parameters

_query_executor

Query executor of which to decrement the reference count.

Can contain NULL.

Precondition: _query_executor is an assignable expression.

◆ BT_QUERY_EXECUTOR_MOVE_REF

#define BT_QUERY_EXECUTOR_MOVE_REF	(	_dst,
		_src
	)

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

This macro effectively moves a query executor 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_query_executor_create_with_method_data()

bt_query_executor* bt_query_executor_create_with_method_data	(	const bt_component_class *	component_class,
		const char *	object_name,
		const bt_value *	params,
		void *	method_data
	)

Creates a query executor to query the object named object_name from the component class component_class with the parameters params and the query user data method_data.

When you call bt_query_executor_query() with the returned query executor, the query method of component_class receives:

object_name as its own object_name parameter.
params as its own params parameter (or bt_value_null if params is NULL).
method_data as its own method_data parameter.

Parameters

[in]	component_class	Component class from which to query the object named object_name.
[in]	object_name	Name of the object to query from component_class.
[in]	params	Parameters for the query operation performed by the query executor to create. Unlike the params parameter of the `bt_graph_add__component__port_added_listener()` functions (see Graph), this parameter does not need to be a map value. Can be `NULL` (equivalent to passing bt_value_null).
[in]	method_data	User data passed as is to the query method of component_class when you call bt_query_executor_query().

Returns: New query executor reference, or NULL on memory error.

Precondition: component_class is not NULL.; object is not NULL.

Postcondition: On success, component_class is frozen.; On success, params is frozen.

◆ bt_query_executor_query()

bt_query_executor_query_status bt_query_executor_query	(	bt_query_executor *	query_executor,
		const bt_value **	result
	)

Performs a query operation using the query executor query_executor, setting *result to the operation's result on success.

This function calls the query executor's target component class's query method, passing:

The object name of query_executor as the object_name parameter.
The query parameters of query_executor as the params parameter.
The query user data of query_executor as the method_data parameter.

The three items above were set when you created query_executor with bt_query_executor_create() or bt_query_executor_create_with_method_data().

Parameters

[in]	query_executor	Query executor to use to execute the query operation.
[out]	result	On success, result is a strong* reference of the query operation's result.

Return values

BT_QUERY_EXECUTOR_QUERY_STATUS_OK	Success.
BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT	Unknown object to query.
BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN	Try again.
BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR	Out of memory.
BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR	Other error.

Precondition: query_executor is not NULL.; result is not NULL.

◆ bt_query_executor_set_logging_level()

bt_query_executor_set_logging_level_status bt_query_executor_set_logging_level	(	bt_query_executor *	query_executor,
		bt_logging_level	logging_level
	)

Sets the logging level of the query executor query_executor to logging_level.

See the logging level property.

Parameters

[in]	query_executor	Query executor of which to set the logging level to logging_level.
[in]	logging_level	New logging level of query_executor.

Return values

BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK Success.

Precondition: query_executor is not NULL.

See also: bt_stream_class_get_logging_level() — Returns the logging level of a query executor.

◆ bt_query_executor_get_logging_level()

bt_logging_level bt_query_executor_get_logging_level ( const bt_query_executor * query_executor )

Returns the logging level of the query executor query_executor.

See the logging level property.

Parameters

[in] query_executor Query executor of which to get the logging level.

Returns: Logging level of query_executor.

Precondition: query_executor is not NULL.

See also: bt_query_executor_set_logging_level() — Sets the logging level of a query executor.

◆ bt_query_executor_add_interrupter()

bt_query_executor_add_interrupter_status bt_query_executor_add_interrupter	(	bt_query_executor *	query_executor,
		const bt_interrupter *	interrupter
	)

Adds the interrupter interrupter to the query executor query_executor.

A component class query method can check whether or not its executor is interrupted (any of its interrupters, including its default interrupter, is set) with bt_query_executor_is_interrupted().

Note

bt_query_executor_create() and bt_query_executor_create_with_method_data() return a query executor which comes with its own default interrupter.

Instead of adding your own interrupter to query_executor, you can set its default interrupter with

bt_interrupter_set(bt_query_executor_borrow_default_interrupter());

Parameters

[in]	query_executor	Query executor to which to add interrupter.
[in]	interrupter	Interrupter to add to query_executor.

Return values

BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK	Success.
BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	Out of memory.

Precondition: query_executor is not NULL.; interrupter is not NULL.

See also: bt_query_executor_borrow_default_interrupter() — Borrows the default interrupter from a query executor.

◆ bt_query_executor_borrow_default_interrupter()

bt_interrupter* bt_query_executor_borrow_default_interrupter ( bt_query_executor * query_executor )

Borrows the default interrupter from the query executor query_executor.

Parameters

[in] query_executor Query executor from which to borrow the default interrupter.

Returns

Borrowed reference of the default interrupter of query_executor.

The returned pointer remains valid as long as query_executor exists.

Precondition: query_executor is not NULL.

See also: bt_query_executor_add_interrupter() — Adds an interrupter to a query executor.

◆ bt_query_executor_is_interrupted()

bt_bool bt_query_executor_is_interrupted ( const bt_query_executor * query_executor )

Returns whether or not the query executor query_executor is interrupted, that is, whether or not any of its interrupters, including its default interrupter, is set.

Parameters

[in] query_executor Query executor to check.

Returns: BT_TRUE if query_executor is interrupted (any of its interrupters is set).

Precondition: query_executor is not NULL.

◆ bt_query_executor_get_ref()

void bt_query_executor_get_ref ( const bt_query_executor * query_executor )

Increments the reference count of the query executor query_executor.

Parameters

[in]

query_executor

Query executor of which to increment the reference count.

Can be NULL.

See also: bt_query_executor_put_ref() — Decrements the reference count of a query executor.

◆ bt_query_executor_put_ref()

void bt_query_executor_put_ref ( const bt_query_executor * query_executor )

Decrements the reference count of the query executor query_executor.

Parameters

[in]

query_executor

Query executor of which to decrement the reference count.

Can be NULL.

See also: bt_query_executor_get_ref() — Increments the reference count of a query executor.

Detailed Description

Property

Type

Creation

Query operation

Property

Interruption

Reference count

Enumeration Type Documentation

◆ bt_query_executor_query_status

◆ bt_query_executor_set_logging_level_status

◆ bt_query_executor_add_interrupter_status

Macro Definition Documentation

◆ BT_QUERY_EXECUTOR_PUT_REF_AND_RESET

◆ BT_QUERY_EXECUTOR_MOVE_REF

Function Documentation

◆ bt_query_executor_create_with_method_data()

◆ bt_query_executor_query()

◆ bt_query_executor_set_logging_level()

◆ bt_query_executor_get_logging_level()

◆ bt_query_executor_add_interrupter()

◆ bt_query_executor_borrow_default_interrupter()

◆ bt_query_executor_is_interrupted()

◆ bt_query_executor_get_ref()

◆ bt_query_executor_put_ref()