lib: prepare the ground for stateful query operations
This patch changes the library (and everything which depends on it) so
that it is possible to make query operations stateful in the future if
needed.
Without this patch, a query operation can return the
`BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN` status. The query
executor's user can then retry the operation until it works, or abandon.
However, there's no way for this query function to keep state between
calls, so the process starts over every time whereas it could have
progressed otherwise (for example, a temporary unresponsive network).
Library changes
===============
This patch does two things to address the limitation above:
* It makes bt_query_executor_create() accept the component class, query
object, and query parameters. It also removes those parameters, as
well as the logging level, from bt_query_executor_query().
This ensures that a given query executor is dedicated to a specific
query operation. Once you create a query executor, you cannot change
the target component class, query object, and query parameters
afterwards.
The initial query executor's logging level is `BT_LOGGING_LEVEL_NONE`.
You can set it before you call bt_query_executor_query() with
bt_query_executor_set_logging_level().
Internally, the query executor keeps a reference on the component
class, a copy of the query object, and a reference on the query
parameters.
* It makes a query method receive a private query executor
(`bt_private_query_executor *`) object, and not receive the logging
level.
A private query executor is a private view of the query executor. This
is where we can eventually add bt_private_query_executor_set_data()
and bt_private_query_executor_get_data() to make the query operation
stateful. From the query method's point of view, the private query
executor is borrowed: there are no bt_private_query_executor_get_ref()
and bt_private_query_executor_put_ref() functions.
You can go from a private query executor to a constant query executor
with bt_private_query_executor_as_query_executor_const(). This is how
you can get the query executor's current logging level with
bt_query_executor_get_logging_level().
To keep the changes minimal, query methods still receive the object
and parameters every time. They are guaranteed, however, that for the
same query executor, they remain unchanged. This guarantee is not
relevant now anyway as there's no way to set and get private data.
Python bindings changes
=======================
* The new `_QueryExecutorCommon` class contains the common properties of
a query executor and a private query executor (`is_interrupted` and
`logging_level`). It requires its subclasses to implement the
_as_query_executor_ptr() method to get the query executor pointer.
* `QueryExecutor` inherits `_QueryExecutorCommon`.
You now build a query executor with the component class, object, and
(optional) query parameters:
query_exec = bt2.QueryExecutor(MySrc, 'avail-servers',
{'blacklist': ['node67']})
You now call the query() method without parameters:
query_exec.query()
You can set the logging level with:
query_exec.logging_level = bt2.LoggingLevel.TRACE
* The new `_PrivateQueryExecutor` class inherits `_QueryExecutorCommon`.
An instance of `_PrivateQueryExecutor` is passed to the query method
during a query operation.
Once the user's query method returns, _bt_query_from_native()
invalidates the private query executor in case the user kept a
reference somewhere. Calling any method of an invalid private query
executor raises `RuntimeError`.
CLI changes
===========
To centralize how query operations are performed in the CLI, all the
sites which need to query use the new cli_query(), implemented in
`src/cli/babeltrace2-query.c`.
cli_query() is similar to the static query() function in
`babeltrace2.c`, which already existed, but it accepts the logging level
directly and returns `bt_query_executor_query_status`.
The static query() function still exists, but calls cli_query() now.
The automatic source discovery feature now uses cli_query() instead of
creating its own query executor.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I3c254325817c2c0091b6c4f0030bc7020443b8e0
Reviewed-on: https://review.lttng.org/c/babeltrace/+/1787
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Simon Marchi <simon.marchi@efficios.com>
34 files changed:
This page took 0.028289 seconds and 4 git commands to generate.