X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Fgraph%2Fquery-executor.h;h=a3d1c6376bbb88bf6ab57b27d868b3525a50e612;hp=c393e6ec7668c9a08d408f8aaf6972c3e40401a9;hb=43c59509042845f8d42c3e99ec74d45fa2dc0908;hpb=1cda4ff4025e4b3f7bd2a861baa51d2113c4cbf9

diff --git a/include/babeltrace2/graph/query-executor.h b/include/babeltrace2/graph/query-executor.h
index c393e6ec..a3d1c637 100644
--- a/include/babeltrace2/graph/query-executor.h
+++ b/include/babeltrace2/graph/query-executor.h
@@ -34,47 +34,547 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-qexec Query executor
+@ingroup api-graph
+
+@brief
+    Executor of \bt_comp_cls object queries.
+
+A <strong><em>query executor</em></strong> is an executor of
+\bt_comp_cls object queries.
+
+A component class can implement a query method to offer one or more
+\em objects depending on the query parameters.
+
+Both the query parameters and the returned objects are \bt_p_val.
+
+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
+<code>source.ctf.lttng-live</code> component class (see
+\bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions
+object to list the available
+<a href="https://lttng.org/docs/#doc-lttng-live">LTTng live</a>
+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
+\ref api-fund-shared-object "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, \bt_voidp 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 \bt_intr 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()
+  \em before you perform the query operation with
+  bt_query_executor_query().
+
+  Then, set the interrupter with bt_interrupter_set().
+
+<h1>Property</h1>
+
+A query executor has the following property:
+
+<dl>
+  <dt>
+    \anchor api-qexec-prop-log-lvl
+    Logging level
+  </dt>
+  <dd>
+    Logging level of the query executor's query operations.
+
+    Use bt_query_executor_set_logging_level() and
+    bt_query_executor_get_logging_level().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_query_executor bt_query_executor;
+
+@brief
+    Query executor.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Alias of bt_query_executor_create_with_method_data()
+    with the \bt_p{method_data} parameter set to \c NULL.
+*/
 extern
 bt_query_executor *bt_query_executor_create(
-		const bt_component_class *component_class, const char *object,
-		const bt_value *params);
+		const bt_component_class *component_class,
+		const char *object_name, const bt_value *params);
+
+/*!
+@brief
+    Creates a query executor to query the object named
+    \bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
+    the parameters \bt_p{params} and the query user data
+    \bt_p{method_data}.
+
+When you call bt_query_executor_query() with the returned query
+executor, the query method of \bt_p{component_class} receives:
+
+- \bt_p{object_name} as its own \bt_p{object_name} parameter.
 
+- \bt_p{params} as its own \bt_p{params} parameter
+  (or #bt_value_null if \bt_p{params} is \c NULL).
+
+- \bt_p{method_data} as its own \bt_p{method_data} parameter.
+
+@param[in] component_class
+    Component class from which to query the object named
+    \bt_p{object_name}.
+@param[in] object_name
+    Name of the object to query from \bt_p{component_class}.
+@param[in] params
+    @parblock
+    Parameters for the query operation performed by the query executor
+    to create.
+
+    Unlike the \bt_p{params} parameter of
+    the <code>bt_graph_add_*_component_*_port_added_listener()</code>
+    functions (see \ref api-graph), this parameter does not need to
+    be a \bt_map_val.
+
+    Can be \c NULL (equivalent to passing #bt_value_null).
+    @endparblock
+@param[in] method_data
+    User data passed as is to the query method of \bt_p{component_class}
+    when you call bt_query_executor_query().
+
+@returns
+    New query executor reference, or \c NULL on memory error.
+
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{object}
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern
 bt_query_executor *bt_query_executor_create_with_method_data(
-		const bt_component_class *component_class, const char *object,
-		const bt_value *params, void *method_data);
+		const bt_component_class *component_class,
+		const char *object_name, const bt_value *params,
+		void *method_data);
+
+/*! @} */
 
+/*!
+@name Query operation
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_query().
+*/
 typedef enum bt_query_executor_query_status {
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_QUERY_EXECUTOR_QUERY_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Unknown object to query.
+	*/
+	BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT	= __BT_FUNC_STATUS_UNKNOWN_OBJECT,
+
+	/*!
+	@brief
+	    Try again.
+	*/
 	BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN		= __BT_FUNC_STATUS_AGAIN,
-	BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR		= __BT_FUNC_STATUS_ERROR,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
 	BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
-	BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT	= __BT_FUNC_STATUS_UNKNOWN_OBJECT,
+
+	/*!
+	@brief
+	    Other error.
+	*/
+	BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR		= __BT_FUNC_STATUS_ERROR,
 } bt_query_executor_query_status;
 
+/*!
+@brief
+    Performs a query operation using the query executor
+    \bt_p{query_executor}, setting \bt_p{*result} to the operation's
+    result on success.
+
+This function calls the query executor's target \bt_comp_cls's
+query method, passing:
+
+- The object name of \bt_p{query_executor} as the
+  \bt_p{object_name} parameter.
+
+- The query parameters of \bt_p{query_executor} as the
+  \bt_p{params} parameter.
+
+- The query user data of \bt_p{query_executor} as the \bt_p{method_data}
+  parameter.
+
+The three items above were set when you created \bt_p{query_executor}
+with bt_query_executor_create() or
+bt_query_executor_create_with_method_data().
+
+@param[in] query_executor
+    Query executor to use to execute the query operation.
+@param[out] result
+    <strong>On success</strong>, \bt_p{*result} is a \em strong
+    reference of the query operation's result.
+
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
+    Success.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
+    Unknown object to query.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
+    Try again.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{result}
+*/
 extern
 bt_query_executor_query_status bt_query_executor_query(
 		bt_query_executor *query_executor, const bt_value **result);
 
+/*! @} */
+
+/*!
+@name Property
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_set_logging_level().
+*/
+typedef enum bt_query_executor_set_logging_level_status {
+	/*!
+	@brief
+	    Success.
+	*/
+	BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK	= __BT_FUNC_STATUS_OK,
+} bt_query_executor_set_logging_level_status;
+
+/*!
+@brief
+    Sets the logging level of the query executor \bt_p{query_executor}
+    to \bt_p{logging_level}.
+
+See the \ref api-qexec-prop-log-lvl "logging level" property.
+
+@param[in] query_executor
+    Query executor of which to set the logging level to
+    \bt_p{logging_level}.
+@param[in] logging_level
+    New logging level of \bt_p{query_executor}.
+
+@retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
+    Success.
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_stream_class_get_logging_level() &mdash;
+    Returns the logging level of a query executor.
+*/
+extern bt_query_executor_set_logging_level_status
+bt_query_executor_set_logging_level(bt_query_executor *query_executor,
+		bt_logging_level logging_level);
+
+/*!
+@brief
+    Returns the logging level of the query executor
+    \bt_p{query_executor}.
+
+See the \ref api-qexec-prop-log-lvl "logging level" property.
+
+@param[in] query_executor
+    Query executor of which to get the logging level.
+
+@returns
+    Logging level of \bt_p{query_executor}.
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_query_executor_set_logging_level() &mdash;
+    Sets the logging level of a query executor.
+*/
+extern bt_logging_level bt_query_executor_get_logging_level(
+		const bt_query_executor *query_executor);
+
+/*! @} */
+
+/*!
+@name Interruption
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_add_interrupter().
+*/
 typedef enum bt_query_executor_add_interrupter_status {
+	/*!
+	@brief
+	    Success.
+	*/
 	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK		= __BT_FUNC_STATUS_OK,
+
+	/*!
+	@brief
+	    Out of memory.
+	*/
 	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_query_executor_add_interrupter_status;
 
+/*!
+@brief
+    Adds the \bt_intr \bt_p{interrupter} to the query executor
+    \bt_p{query_executor}.
+
+A \bt_comp_cls 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
+    @parblock
+    bt_query_executor_create() and
+    bt_query_executor_create_with_method_data() return a query executor
+    which comes with its own <em>default interrupter</em>.
+
+    Instead of adding your own interrupter to \bt_p{query_executor}, you
+    can set its default interrupter with
+
+    @code
+    bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
+    @endcode
+    @endparblock
+
+@param[in] query_executor
+    Query executor to which to add \bt_p{interrupter}.
+@param[in] interrupter
+    Interrupter to add to \bt_p{query_executor}.
+
+@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
+    Success.
+@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{interrupter}
+
+@sa bt_query_executor_borrow_default_interrupter() &mdash;
+    Borrows the default interrupter from a query executor.
+*/
 extern bt_query_executor_add_interrupter_status
 bt_query_executor_add_interrupter(bt_query_executor *query_executor,
 		const bt_interrupter *interrupter);
 
+/*!
+@brief
+    Borrows the default \bt_intr from the query executor
+    \bt_p{query_executor}.
+
+@param[in] query_executor
+    Query executor from which to borrow the default interrupter.
+
+@returns
+    @parblock
+    \em Borrowed reference of the default interrupter of
+    \bt_p{query_executor}.
+
+    The returned pointer remains valid as long as \bt_p{query_executor}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_query_executor_add_interrupter() &mdash;
+    Adds an interrupter to a query executor.
+*/
 extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
 		bt_query_executor *query_executor);
 
-typedef enum bt_query_executor_set_logging_level_status {
-	BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK	= __BT_FUNC_STATUS_OK,
-} bt_query_executor_set_logging_level_status;
+/*!
+@brief
+    Returns whether or not the query executor \bt_p{query_executor}
+    is interrupted, that is, whether or not any of its \bt_p_intr,
+    including its default interrupter, is set.
 
-extern bt_query_executor_set_logging_level_status
-bt_query_executor_set_logging_level(bt_query_executor *query_executor,
-		bt_logging_level logging_level);
+@param[in] query_executor
+    Query executor to check.
+
+@returns
+    #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
+    interrupters is set).
+
+@bt_pre_not_null{query_executor}
+*/
+extern bt_bool bt_query_executor_is_interrupted(
+		const bt_query_executor *query_executor);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the query executor \bt_p{query_executor}.
+
+@param[in] query_executor
+    @parblock
+    Query executor of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_query_executor_put_ref() &mdash;
+    Decrements the reference count of a query executor.
+*/
+extern void bt_query_executor_get_ref(const bt_query_executor *query_executor);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the query executor \bt_p{query_executor}.
+
+@param[in] query_executor
+    @parblock
+    Query executor of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_query_executor_get_ref() &mdash;
+    Increments the reference count of a query executor.
+*/
+extern void bt_query_executor_put_ref(const bt_query_executor *query_executor);
+
+/*!
+@brief
+    Decrements the reference count of the query executor
+    \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
+
+@param _query_executor
+    @parblock
+    Query executor of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_query_executor}
+*/
+#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor)	\
+	do {							\
+		bt_query_executor_put_ref(_query_executor);	\
+		(_query_executor) = NULL;			\
+	} while (0)
+
+/*!
+@brief
+    Decrements the reference count of the query executor \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a query executor reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src)		\
+	do {						\
+		bt_query_executor_put_ref(_dst);	\
+		(_dst) = (_src);			\
+		(_src) = NULL;				\
+	} while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }