celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject celix git commit: CELIX-368: Adds readme for C++ Dependency Manager
Date Thu, 21 Jul 2016 13:14:50 GMT
Repository: celix
Updated Branches:
  refs/heads/develop 8778ce59f -> cbb2191e0


CELIX-368: Adds readme for C++ Dependency Manager


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

Branch: refs/heads/develop
Commit: cbb2191e037d3885875cd130973ccca888a9f095
Parents: 8778ce5
Author: Pepijn Noltes <pepijnnoltes@gmail.com>
Authored: Thu Jul 21 15:14:22 2016 +0200
Committer: Pepijn Noltes <pepijnnoltes@gmail.com>
Committed: Thu Jul 21 15:14:22 2016 +0200

----------------------------------------------------------------------
 dependency_manager/README.md       | 14 ++++----
 dependency_manager_cxx/README.md   | 64 +++++++++++++++++++++++++++++++++
 documents/best_practices/README.md |  2 +-
 3 files changed, 73 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/celix/blob/cbb2191e/dependency_manager/README.md
----------------------------------------------------------------------
diff --git a/dependency_manager/README.md b/dependency_manager/README.md
index d2201bf..2f9b2fd 100644
--- a/dependency_manager/README.md
+++ b/dependency_manager/README.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-The Dependency Manager contains a static library which can be iuse to manage (dynamic) services
on a higher abstraction level in a declarive style. 
+The Dependency Manager contains a static library which can be used to manage (dynamic) services
on a higher abstraction level in a declarative style. 
 The Apache Celix Dependency Manager is inspired by the [Apache Felix Dependency Manager](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html).
 
 ## Components
@@ -31,7 +31,7 @@ The Dependency Manager consist out of four main parts: `DM (Dependency Manager)
 
 ### DM Activator
 
-The `DM Activator implements a "normal" Celix bundle activator and depends on four functions
which needs to be implemented by the user of the Depedency Manager:
+The `DM Activator` implements a "normal" Celix bundle activator and depends on four functions
which needs to be implemented by the user of the Depedency Manager:
  - `dm_create` : Should be used to allocated and initialize a dm activator structure. If
needed this structure can be used to store object during the lifecycle of the bundle.
  - `dm_init` : Should be used to interact with the `Dependency Manager`. Here a user can
components, service dependencies and provided services. 
  - `dm_destroy` : Should be used to deinitialize and deallocate objects created in the `dm_create`
function.
@@ -43,7 +43,7 @@ The `Dependency Manager` act as an entry point to add or remove DM Components.
T
 
 ### DM Component
 
-The `DM Component` manages the life cycle of the component. For example, when all required
service dependencies are aviable the `DM Component` will call the `start` specified callback
function of the component. 
+The `DM Component` manages the life cycle of a component. For example, when all required
service dependencies are available the `DM Component` will call the `start` specified callback
function of the component. 
 
 The `component_setImplementation` function can be used to specify which component handle
to use. 
 The `component_addInterface` can be used to specify one additional service provided by the
component. 
@@ -53,9 +53,11 @@ The `component_addServiceDependency` can be used to specify one additional
servi
 
 The `DM Service Dependency` can be used to specify service dependencies for a component.
i
 
-When these dependencies are set to required the `DM Component` will ensure that components
will only be started when all quired dependencies are aviable and stop the component if any
of the required dependencies are removed. This feature should prevent a lot of boiler plating
code compared to usign a service tracker or services references directly. 
+When these dependencies are set to required the `DM Component` will ensure that components
will only be started when all required dependencies are available and stop the component if
any of the required dependencies are removed. 
+This feature should prevent a lot of boiler plating code compared to using a service tracker
or services references directly. 
 
-A service dependency update strategy can also be specified. Default this strategy is set
to `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` this stragegy will stop and start (suspend) a
component when any of the specified service dependencies change (are removed, added or modified).
When correclty used this strategy removes the need for locking services during updates/invocation.
See the dependency manager example for more details.
+A service dependency update strategy can also be specified. Default this strategy is set
to `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` this strategy will stop and start (suspend) a
component when any of the specified service dependencies change (are removed, added or modified).

+When correctly used this strategy removes the need for locking services during updates/invocation.
See the dependency manager example for more details.
 
 The `serviceDependency_setCallbacks` function can be used to specify the function callback
used when services are added, set, removed or modified. 
 The `serviceDependency_setRequired` function can be used to specify if a service dependency
is required.
@@ -118,4 +120,4 @@ For more information examples please see
 - [Best practices](../documents/best_practices/README.md): A introduction how to work with
services using the dependency manager
 - [The Dependency Manager API](public/include): The dependency manager header files
 - [Best practice example](../examples/best_practice_example): A best practice example (also
refered to in the Best practices documentation
-- [Dm example](../examples/dm_example): A DM example project.  
+- [Dm example](../examples/dm_example): A DM example.  

http://git-wip-us.apache.org/repos/asf/celix/blob/cbb2191e/dependency_manager_cxx/README.md
----------------------------------------------------------------------
diff --git a/dependency_manager_cxx/README.md b/dependency_manager_cxx/README.md
new file mode 100644
index 0000000..f147131
--- /dev/null
+++ b/dependency_manager_cxx/README.md
@@ -0,0 +1,64 @@
+# Apache Celix C++ Dependency Manager
+
+## Introduction
+
+The C++ Dependency Manager contains a static library which can be used to manage (dynamic)
services on a higher abstraction level in a declarative style. 
+The Apache Celix C++ Dependency Manager is inspired by the [Apache Felix Dependency Manager](http://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html).
+
+The C++ Dependency Manager uses fluent interface to make specifying DM components and service
dependencies very concise.
+
+
+## C++ and C Dependency Manager
+
+The C++ Dependency Manager is build on top of the C Dependency Manager.
+To get an good overview of the C++ Dependency Manager alse read the [Dependency Manager documentation](../dependency_manager/README.md)

+
+## DM Parts
+
+The C++ Dependency Manager consist out of four main parts: `celix::dm::DmActivator`, `celix::dm::DependencyManager`,
`celix::dm::Component` and `celix::dm::ServiceDependency`.
+
+### DmActivator
+
+The `DmActivator` class should be inherited by a bundle specific Activator. 
+
+- The static `DmActivator::create` method needs to be implemented and should return a bundle
specific subclass instance of the DmActivator.
+- The `DmActivator::init` method should be overridden and can be used to specify which components
to use in the bundle.
+- The `DmActivator::deinit` method can be ocerridden if some cleanup is needed when a bundle
is stopped.
+
+### Dependency Manager
+
+The `DependencyManager` act as an entry point to add or remove (DM) Components. 
+
+### Component
+
+
+
+The (DM) `Component` manages the life cycle of a component (of the template type T). For
example, when all required service dependencies are available the `Component` will call the
`start` specified callback function of the component.
+
+The `Component::setInstance` can be used to set the component instance to used. If no instance
is set the (DM) `Component` will (lazy) create a component instance using the default constructor.
+The `component::addInterface` can be used to specify one additional C service provided by
the component.
+The `component::addCInterface` can be used to specify one additional C++ service provided
by the component. 
+The `component::add` can be used to specify one additional service dependency.
+
+### ServiceDependency and CServiceDependency
+
+The (DM) `ServiceDependency` can be used to specify C++ service dependencies for a component.
+The (DM) `CServiceDependency` can be used to specify C service dependencies for a component.
+
+When these dependencies are set to required the `Component` will ensure that components will
only be started when all required dependencies are available and stop the component if any
of the required dependencies are removed.
+This feature should prevent a lot of boiler plating code compared to using a service tracker
or services references directly. 
+
+A service dependency update strategy can also be specified. Default this strategy is set
to `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` this strategy will stop and start (suspend) a
component when any of the specified service dependencies change (are removed, added or modified).

+When correctly used this strategy removes the need for locking services during updates/invocation.
See the dependency manager_cxx example for more details.
+
+The `(C)ServiceDependency::setCallbacks` function can be used to specify the function callback
used when services are added, set, removed or modified. 
+The `(C)ServiceDependency::setRequired` function can be used to specify if a service dependency
is required.
+The `(C)ServiceDependency::setStrategy` function can be used to specify a service dependency
update strategy (suspend or locking).
+
+### References
+
+For more information examples please see
+
+- [The C++ Dependency Manager API](include/celix/dm): The c++ dependency manager header files
+- [Dm C++ example](../examples/dm_example_cxx): A DM C++ example.
+- [Best practices](../documents/best_practices/README.md): A introduction how to work with
services using the C dependency manager

http://git-wip-us.apache.org/repos/asf/celix/blob/cbb2191e/documents/best_practices/README.md
----------------------------------------------------------------------
diff --git a/documents/best_practices/README.md b/documents/best_practices/README.md
index 4a16cc8..9671b2d 100644
--- a/documents/best_practices/README.md
+++ b/documents/best_practices/README.md
@@ -1,4 +1,4 @@
-# Best Practice Example
+# Apache Celix Best Practices
 
 ## Intro 
 


Mime
View raw message