This is an automated email from the ASF dual-hosted git repository.
pnoltes pushed a commit to branch feature/87-refactor-use-services
in repository https://gitbox.apache.org/repos/asf/celix.git
The following commit(s) were added to
refs/heads/feature/87-refactor-use-services by this push:
new 3d1d8bca gh-87: Update useService doxygen documentation
3d1d8bca is described below
commit 3d1d8bca2d8f5b5917d388a21f538cee7f863b38
Author: Pepijn Noltes <pnol...@apache.org>
AuthorDate: Sun Mar 24 16:22:03 2024 +0100
gh-87: Update useService doxygen documentation
---
libs/framework/include/celix/BundleContext.h | 24 ++++++------
libs/framework/include/celix_bundle_context.h | 54 ++++++++++++++++-----------
2 files changed, 45 insertions(+), 33 deletions(-)
diff --git a/libs/framework/include/celix/BundleContext.h
b/libs/framework/include/celix/BundleContext.h
index 1bb89fae..608fa37f 100644
--- a/libs/framework/include/celix/BundleContext.h
+++ b/libs/framework/include/celix/BundleContext.h
@@ -106,14 +106,16 @@ namespace celix {
/**
* @brief Use a service registered in the Celix framework using a
fluent builder API.
*
- * @deprecated celix_bundleContext_useService are deprecated and
should be considered test utils functions. In
- * operational code use celix_bundleContext_trackService* combined
with celix_bundleContext_useTrackedService*
- * functions instead.
+ * @warning Cannot be called from the Celix event thread.
+ *
+ * @note celix::BundleContext::useService should be considered a test
util method.
+ * For production code, use celix::BundleContext::trackServices
combined with use callback methods on the
+ * service tracker instead.
*
* The service use can be fine tuned using the returned
UseServiceBuilder API.
*
* With this API a Celix service can be used by providing use
functions.
- * The use function will be executed on the Celix event thread and the
Celix framework
+ * The use function will be executed on the calling thread and the
Celix framework
* will ensure that the service cannot be removed while in use.
*
* If there are more 1 matching service, the highest ranking service
will be used.
@@ -134,7 +136,6 @@ namespace celix {
* @return A UseServiceBuilder object.
*/
template<typename I>
- [[deprecated]]
UseServiceBuilder<I> useService(const std::string& name = {}) {
return UseServiceBuilder<I>{cCtx, celix::typeName<I>(name), true};
}
@@ -142,15 +143,17 @@ namespace celix {
/**
* @brief Use services registered in the Celix framework using a
fluent builder API.
*
- * @deprecated celix_bundleContext_useService are deprecated and
should be considered test utils functions. In
- * operational code use celix_bundleContext_trackService* combined
with celix_bundleContext_useTrackedService*
- * functions instead.
+ * @warning Cannot be called from the Celix event thread.
+ *
+ * @note celix::BundleContext::useServices should be considered a test
util method.
+ * For production code, use celix::BundleContext::trackServices
combined with use callback methods on the
+ * service tracker instead.
*
* The service use can be fine tuned using the returned
UseServiceBuilder API.
*
* With this API Celix services can be used by providing use functions.
- * The use function will be executed on the Celix event thread and the
Celix framework
- * will ensure that the service cannot be removed while in use.
+ * The use function will be executed on the calling thread and the
Celix framework
+ * will ensure that the used services cannot be removed while in use.
*
* The use callbacks will be called for every matching service found.
*
@@ -167,7 +170,6 @@ namespace celix {
* @return A UseServiceBuilder object.
*/
template<typename I>
- [[deprecated]]
UseServiceBuilder<I> useServices(const std::string& name = {}) {
return UseServiceBuilder<I>{cCtx, celix::typeName<I>(name), false};
}
diff --git a/libs/framework/include/celix_bundle_context.h
b/libs/framework/include/celix_bundle_context.h
index e93d88aa..890de3fe 100644
--- a/libs/framework/include/celix_bundle_context.h
+++ b/libs/framework/include/celix_bundle_context.h
@@ -376,7 +376,8 @@ typedef struct celix_service_filter_options {
* @param opts The pointer to the filter options.
* @return If found a valid service id (>= 0) if not found -1.
*/
-CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_findServiceWithOptions(celix_bundle_context_t *ctx, const
celix_service_filter_options_t *opts);
+CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_findServiceWithOptions(celix_bundle_context_t* ctx,
+ const
celix_service_filter_options_t* opts);
/**
* @brief Finds the services conform the provider filter options and returns a
list of the found service ids.
@@ -385,18 +386,21 @@ CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_findServiceWithOptions(celix_bun
* @param opts The pointer to the filter options.
* @return A array list with as value a long int.
*/
-CELIX_FRAMEWORK_EXPORT celix_array_list_t*
celix_bundleContext_findServicesWithOptions(celix_bundle_context_t *ctx, const
celix_service_filter_options_t *opts);
+CELIX_FRAMEWORK_EXPORT celix_array_list_t*
+celix_bundleContext_findServicesWithOptions(celix_bundle_context_t* ctx, const
celix_service_filter_options_t* opts);
/**
* @brief Use the service with the provided service id using the provided
callback. The Celix framework will ensure that
* the targeted service cannot be removed during the callback.
*
- * @deprecated celix_bundleContext_useService are deprecated and should be
considered test utils functions. In
- * operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService* functions
- * instead.
+ * @warning Cannot be called from the Celix event thread.
*
- * The svc is should only be considered valid during the callback.
- * If no service is found, the callback will not be invoked and this function
will return false immediately.
+ * @deprecated celix_bundleContext_useServiceWithId is deprecated and should
be considered test utils functions. In
+ * operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService*
+ * functions instead.
+ *
+ * The Celix framework will ensure that the targeted service cannot be removed
during the callback and the callback
+ * is called on the calling thread.
*
* This function will block until the callback is finished. As result it is
possible to provide callback data from the
* stack.
@@ -407,7 +411,7 @@ CELIX_FRAMEWORK_EXPORT celix_array_list_t*
celix_bundleContext_findServicesWithO
* service id (sanity check)
* @param callbackHandle The data pointer, which will be used in the callbacks
* @param use The callback, which will be called when service is retrieved.
- * @param bool returns true if a service was found.
+ * @param bool returns true if a service was found and the callback was called.
*/
CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithId(celix_bundle_context_t* ctx,
long serviceId,
@@ -418,11 +422,14 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithId(celi
/**
* @brief Use the highest ranking service with the provided service name using
the provided callback.
*
- * @deprecated celix_bundleContext_useService are deprecated and should be
considered test utils functions. In
+ * @warning Cannot be called from the Celix event thread.
+ *
+ * @deprecated celix_bundleContext_useService is deprecated and should be
considered test utils functions. In
* operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService* functions
* instead.
*
- * The Celix framework will ensure that the targeted service cannot be removed
during the callback.
+ * The Celix framework will ensure that the targeted service cannot be removed
during the callback and the callback
+ * is called on the calling thread.
*
* The svc is should only be considered valid during the callback.
* If no service is found, the callback will not be invoked and this function
will return false immediately.
@@ -434,7 +441,7 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithId(celi
* @param serviceName the required service name.
* @param callbackHandle The data pointer, which will be used in the
callbacks
* @param use The callback, which will be called when service is retrieved.
- * @return True if a service was found.
+ * @return True if a service was found and the callback was called.
*/
CELIX_FRAMEWORK_DEPRECATED_EXPORT bool celix_bundleContext_useService(
celix_bundle_context_t *ctx,
@@ -446,11 +453,14 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useService(
/**
* @brief Use the services with the provided service name using the provided
callback.
*
- * @deprecated celix_bundleContext_useService are deprecated and should be
considered test utils functions. In
+ * @warning Cannot be called from the Celix event thread.
+ *
+ * @deprecated celix_bundleContext_useServices is deprecated and should be
considered test utils functions. In
* operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService* functions
* instead.
*
- * The Celix framework will ensure that the targeted service cannot be removed
during the callback.
+ * The Celix framework will ensure that the targeted service cannot be removed
during the callback and the callback
+ * is called on the calling thread.
*
* The svc is should only be considered valid during the callback.
* If no service is found, the callback will not be invoked and this function
will return 0 immediately.
@@ -462,7 +472,7 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useService(
* @param serviceName the required service name.
* @param callbackHandle The data pointer, which will be used in the
callbacks
* @param use The callback, which will be called for every service found.
- * @return The number of services found and called
+ * @return The number of services found and called.
*/
CELIX_FRAMEWORK_DEPRECATED_EXPORT size_t celix_bundleContext_useServices(
celix_bundle_context_t *ctx,
@@ -538,9 +548,9 @@ typedef struct celix_service_use_options {
/**
* @brief Use the highest ranking service satisfying the provided service
filter options using the provided callback.
*
- * @deprecated celix_bundleContext_useService are deprecated and should be
considered test utils functions. In
- * operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService* functions
- * instead.
+ * @note celix_bundleContext_useService should be considered a test util
function.
+ * For production code, use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService*
+ * functions instead.
*
* The Celix framework will ensure that the targeted service cannot be removed
during the callback.
*
@@ -555,7 +565,7 @@ typedef struct celix_service_use_options {
* @param opts The required options. Note that the serviceName is required.
* @return True if a service was found.
*/
-CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithOptions(
+CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithOptions(
celix_bundle_context_t *ctx,
const celix_service_use_options_t *opts);
@@ -563,9 +573,9 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithOptions
/**
* @brief Use the services with the provided service filter options using the
provided callback.
*
- * @deprecated celix_bundleContext_useService are deprecated and should be
considered test utils functions. In
- * operational code use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService* functions
- * instead.
+ * @note celix_bundleContext_useService should be considered test utils
functions.
+ * For production code, use celix_bundleContext_trackService* combined with
celix_bundleContext_useTrackedService*
+ * functions instead.
*
* The Celix framework will ensure that the targeted service cannot be removed
during the callback.
*
@@ -580,7 +590,7 @@ CELIX_FRAMEWORK_DEPRECATED_EXPORT bool
celix_bundleContext_useServiceWithOptions
* @param opts The required options. Note that the serviceName is required.
* @return The number of services found and called
*/
-CELIX_FRAMEWORK_DEPRECATED_EXPORT size_t
celix_bundleContext_useServicesWithOptions(
+CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServicesWithOptions(
celix_bundle_context_t *ctx,
const celix_service_use_options_t *opts);
