celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject [2/3] celix git commit: CELIX-368: Adds documentiation the dependency manager headers
Date Thu, 21 Jul 2016 09:55:52 GMT
CELIX-368: Adds documentiation the dependency manager headers


Project: http://git-wip-us.apache.org/repos/asf/celix/repo
Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/24fd5b42
Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/24fd5b42
Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/24fd5b42

Branch: refs/heads/develop
Commit: 24fd5b4212e2ead76865039e6bbc94b359835c29
Parents: 5d3719c
Author: Pepijn Noltes <pepijnnoltes@gmail.com>
Authored: Thu Jul 21 11:54:17 2016 +0200
Committer: Pepijn Noltes <pepijnnoltes@gmail.com>
Committed: Thu Jul 21 11:54:17 2016 +0200

----------------------------------------------------------------------
 dependency_manager/README.md                    |  5 +-
 .../public/include/dm_activator.h               | 15 +++++
 .../public/include/dm_component.h               | 58 ++++++++++++++++-
 .../public/include/dm_dependency_manager.h      | 21 +++++-
 .../public/include/dm_service_dependency.h      | 68 +++++++++++++++++++-
 5 files changed, 160 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/celix/blob/24fd5b42/dependency_manager/README.md
----------------------------------------------------------------------
diff --git a/dependency_manager/README.md b/dependency_manager/README.md
index 9a39c52..b0a3a3c 100644
--- a/dependency_manager/README.md
+++ b/dependency_manager/README.md
@@ -63,7 +63,7 @@ The `serviceDependency_setStrategy` function can be used to specify a service
de
 
 ### Snippets
 
-### DM Bundle Activator
+#### DM Bundle Activator
 
 The next snippet shows a dm bundle activator and how to add components to the dependency
manager.
 ```C
@@ -112,7 +112,8 @@ celix_status_t dm_destroy(void * userData, bundle_context_pt context,
dm_depende
 }  
 ```
 
-TODOS
+TODOS:
+
     1. add cmp callbacks
     1. add interface
     1. add service dependency and callbacks

http://git-wip-us.apache.org/repos/asf/celix/blob/24fd5b42/dependency_manager/public/include/dm_activator.h
----------------------------------------------------------------------
diff --git a/dependency_manager/public/include/dm_activator.h b/dependency_manager/public/include/dm_activator.h
index 898d53f..521800a 100644
--- a/dependency_manager/public/include/dm_activator.h
+++ b/dependency_manager/public/include/dm_activator.h
@@ -37,8 +37,23 @@ extern "C" {
 #include "celix_errno.h"
 #include "dm_dependency_manager.h"
 
+/**
+ * Should be implemented by a bundle specific DM activator.
+ * Should allocate and initialize a bundle specific activator struct.
+ */
 celix_status_t dm_create(bundle_context_pt context, void ** userData);
+
+/**
+ * Should be implemented by a bundle specific DM activator.
+ * Will be called after the dm_create function.
+ * Can be used to specify with use of the provided dependency manager the bundle specific
components.
+ */
 celix_status_t dm_init(void * userData, bundle_context_pt context, dm_dependency_manager_pt
manager);
+
+/**
+ * Should be implemented by a bundle specific DM activator.
+ * Should deinitialize and deallocate the undle specific activator struct.
+ */
 celix_status_t dm_destroy(void * userData, bundle_context_pt context, dm_dependency_manager_pt
manager);
 
 #ifdef __cplusplus

http://git-wip-us.apache.org/repos/asf/celix/blob/24fd5b42/dependency_manager/public/include/dm_component.h
----------------------------------------------------------------------
diff --git a/dependency_manager/public/include/dm_component.h b/dependency_manager/public/include/dm_component.h
index 997bd1a..d4f09a8 100644
--- a/dependency_manager/public/include/dm_component.h
+++ b/dependency_manager/public/include/dm_component.h
@@ -53,10 +53,29 @@ typedef int (*start_fpt)(void *userData);
 typedef int (*stop_fpt)(void *userData);
 typedef int (*deinit_fpt)(void *userData);
 
+/**
+ * Creates a DM Component
+ * Caller has ownership.
+ */
 celix_status_t component_create(bundle_context_pt context, const char* name, dm_component_pt
*component);
+
+/**
+ * Destroys a DM Component
+ */
 void component_destroy(dm_component_pt component);
 
+/**
+ * Adds a C interface to provide as service to the Celix framework.
+ *
+ * @param serviceName the service name.
+ * @param version The version of the interface (e.g. "1.0.0"), Can be a NULL pointer.
+ * @param properties To (meta) properties to provide with the service. Can be a NULL pointer.
+ */
 celix_status_t component_addInterface(dm_component_pt component, const char* serviceName,
const char* serviceVersion, const void* service, properties_pt properties);
+
+/**
+ * Sets the implementation of the component. e.g. the component handle/self/this pointer.
+ */
 celix_status_t component_setImplementation(dm_component_pt component, void* implementation);
 
 /**
@@ -64,15 +83,45 @@ celix_status_t component_setImplementation(dm_component_pt component,
void* impl
  */
 celix_status_t component_getInterfaces(dm_component_pt component, array_list_pt *servicesNames);
 
+/**
+ * Adds a C service dependency to the component
+ */
 celix_status_t component_addServiceDependency(dm_component_pt component, dm_service_dependency_pt
dep);
+
+/**
+ * Removes a C service dependency to the component
+ */
 celix_status_t component_removeServiceDependency(dm_component_pt component, dm_service_dependency_pt
dependency);
 
+/**
+ * Returns the current state of the component.
+ */
 dm_component_state_t component_currentState(dm_component_pt cmp);
+
+/**
+ * Returns the implementation of the component. e.g. the component handle/self/this pointer.
+ */
 void * component_getImplementation(dm_component_pt cmp);
+
+/**
+ * Returns the DM component name. This is used when printing information about the component.
+ */
 const char * component_getName(dm_component_pt cmp);
 
+/**
+ * Returns bundle context for the bundle where this DM component is part of.
+ */
 celix_status_t component_getBundleContext(dm_component_pt component, bundle_context_pt *out);
 
+/**
+ * Set the component life cycle callbacks.
+ * The first argument will be the component implementation (@see component_getImplementation)
+ */
+celix_status_t component_setCallbacks(dm_component_pt component, init_fpt init, start_fpt
start, stop_fpt stop, deinit_fpt deinit);
+
+/**
+ * Set the component life cycle callbacks using a MACRO for improving the type safety.
+ */
 #define component_setCallbacksSafe(dmCmp, type, init, start, stop, deinit) \
     do {  \
         int (*tmp_init)(type)   = (init); \
@@ -82,12 +131,15 @@ celix_status_t component_getBundleContext(dm_component_pt component,
bundle_cont
         component_setCallbacks((dmCmp), (init_fpt)tmp_init, (start_fpt)tmp_start, (stop_fpt)tmp_stop,
(deinit_fpt)tmp_deinit); \
     } while(0)
 
-celix_status_t component_setCallbacks(dm_component_pt component, init_fpt init, start_fpt
start, stop_fpt stop, deinit_fpt deinit);
-
 /**
- * returns a dm_component_info_pt. Caller has ownership.
+ * Create a DM Component info struct. Containing information about the component.
+ * Caller has ownership.
  */
 celix_status_t component_getComponentInfo(dm_component_pt component, dm_component_info_pt
*info);
+
+/**
+ * Destroys a DM Component info struct.
+ */
 void component_destroyComponentInfo(dm_component_info_pt info);
 
 #ifdef __cplusplus

http://git-wip-us.apache.org/repos/asf/celix/blob/24fd5b42/dependency_manager/public/include/dm_dependency_manager.h
----------------------------------------------------------------------
diff --git a/dependency_manager/public/include/dm_dependency_manager.h b/dependency_manager/public/include/dm_dependency_manager.h
index 339fa55..9ee8ae5 100644
--- a/dependency_manager/public/include/dm_dependency_manager.h
+++ b/dependency_manager/public/include/dm_dependency_manager.h
@@ -39,17 +39,36 @@ extern "C" {
 
 typedef struct dm_dependency_manager *dm_dependency_manager_pt;
 
+/**
+ * Creates a dependency manager.
+ * Caller has ownership.
+ */
 celix_status_t dependencyManager_create(bundle_context_pt context, dm_dependency_manager_pt
*manager);
+
+/**
+ * Destroys the provided dependency manager
+ */
 void dependencyManager_destroy(dm_dependency_manager_pt manager);
 
+/**
+ * Adds a DM component to the dependency manager
+ */
 celix_status_t dependencyManager_add(dm_dependency_manager_pt manager, dm_component_pt component);
 
+/**
+ * Removes all DM components from the dependency manager
+ */
 celix_status_t dependencyManager_removeAllComponents(dm_dependency_manager_pt manager);
 
 /**
- * returns a dm_ of dm_dependency_manager_info. Caller has ownership.
+ * Create and returns a DM Info struct. Which contains information about the state of the
DM components
+ * Caller has ownership.
  */
 celix_status_t dependencyManager_getInfo(dm_dependency_manager_pt manager, dm_dependency_manager_info_pt
*info);
+
+/**
+ * Destroys a DM info struct.
+ */
 void dependencyManager_destroyInfo(dm_dependency_manager_pt manager, dm_dependency_manager_info_pt
info);
 
 #ifdef __cplusplus

http://git-wip-us.apache.org/repos/asf/celix/blob/24fd5b42/dependency_manager/public/include/dm_service_dependency.h
----------------------------------------------------------------------
diff --git a/dependency_manager/public/include/dm_service_dependency.h b/dependency_manager/public/include/dm_service_dependency.h
index ed19b55..bed9379 100644
--- a/dependency_manager/public/include/dm_service_dependency.h
+++ b/dependency_manager/public/include/dm_service_dependency.h
@@ -55,17 +55,78 @@ typedef celix_status_t (*service_change_with_ref_fpt)(void *handle, service_refe
 typedef celix_status_t (*service_remove_with_ref_fpt)(void *handle, service_reference_pt
reference, const void* service);
 typedef celix_status_t (*service_swap_with_ref_fpt)(void *handle, service_reference_pt oldReference,
const void* oldService, service_reference_pt newReference, const void* newService);
 
+/**
+ * Create a service dependency.
+ * Caller has ownership.
+ */
 celix_status_t serviceDependency_create(dm_service_dependency_pt *dependency_ptr);
+
+/**
+ * Destroys a service dependency.
+ * Caller has ownership.
+ */
 celix_status_t serviceDependency_destroy(dm_service_dependency_pt *dependency_ptr);
 
+/**
+ * Specify if the service dependency is required. default is false
+ */
 celix_status_t serviceDependency_setRequired(dm_service_dependency_pt dependency, bool required);
+
+/**
+ * Specify if the service dependency update strategy.
+ *
+ * For DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING the component is expected to use locking mechanismes
when updating
+ * and invoking services.
+ *
+ * For DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND the component is stopped/started
+ * when services are set,added, modified or removed.
+ * It is the responsibility of the component to ensure that no
+ * service invocation is possible or happening when the component stop callback is finished.
+ *
+ * Default strategy is DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND
+ */
 celix_status_t serviceDependency_setStrategy(dm_service_dependency_pt dependency,dm_service_dependency_strategy_t
strategy);
+
+/**
+ * Return the service dependency update strategy.
+ */
 celix_status_t serviceDependency_getStrategy(dm_service_dependency_pt dependency,dm_service_dependency_strategy_t*
strategy);
+
+/**
+ * Set the service name, version range and filter.
+ *
+ * @param serviceName The service name. Must have a value.
+ * @param serviceVersionRange The service version range, can be a NULL pointer.
+ * @param filter The (additional) filter to use (e.g. "(location=front)"). Can be a NULL
pointer.
+ */
 celix_status_t serviceDependency_setService(dm_service_dependency_pt dependency, const char*
serviceName, const char* serviceVersionRange, const char* filter);
+
+/**
+ * Returns the service depenendy filter.
+ */
 celix_status_t serviceDependency_getFilter(dm_service_dependency_pt dependency, const char**
filter);
 
+/**
+ * Set the set, add, change, remove and swap function callbacks when services specified by
the service dependency
+ * are (respectively) set, added, changed, removed or swapped.
+ * The first argument of the callbacks will be the component implement (@see component_getImplementation)
+ * The second the argument a pointer to an instance of a service struct of the specified
service dependency.
+ */
 celix_status_t serviceDependency_setCallbacks(dm_service_dependency_pt dependency, service_set_fpt
set, service_add_fpt add, service_change_fpt change, service_remove_fpt remove, service_swap_fpt
swap);
+
+/**
+ * Set the set, add, change, remove and swap function callbacks when services specified by
the service dependency
+ * are (respectively) set, added, changed, removed or swapped.
+ * The first argument of the callbacks will be the component implement (@see component_getImplementation)
+ * The second argument of th callbacks will be a pointer to an instance of a service struct
of the specified service dependency.
+ * The third argument of th callbacks will be a pointer to a service reference of the a service
instance of the specified service dependency.
+ */
 celix_status_t serviceDependency_setCallbacksWithServiceReference(dm_service_dependency_pt
dependency, service_set_with_ref_fpt set, service_add_with_ref_fpt add, service_change_with_ref_fpt
change, service_remove_with_ref_fpt remove, service_swap_with_ref_fpt swap);
+
+/**
+ * Specifies which field member (pointer to) to update when a service dependencies is set.
+ * If provided the provided service_lock will be used for locking when updating the service
instance.
+ */
 celix_status_t serviceDependency_setAutoConfigure(dm_service_dependency_pt dependency, celix_thread_mutex_t
*service_lock, const void** field);
 
 #define serviceDependency_setCallbacksSafe(dep, cmpType, servType, set, add, change, remove,
swap) \
@@ -86,9 +147,14 @@ celix_status_t serviceDependency_setAutoConfigure(dm_service_dependency_pt
depen
 celix_status_t serviceDependency_setCallbackHandle(dm_service_dependency_pt dependency, void*
handle);
 
 /**
- * Return a service dependency info. The caller is the owner
+ * Creates a service dependency info. The service dependency info struct contains information
about the service dependency.
+ * The caller is the owner
  */
 celix_status_t serviceDependency_getServiceDependencyInfo(dm_service_dependency_pt, dm_service_dependency_info_pt
*info);
+
+/**
+ * Destroy a provided service dependency info struct.
+ */
 void dependency_destroyDependencyInfo(dm_service_dependency_info_pt info);
 
 #ifdef __cplusplus


Mime
View raw message