Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id D8730200B4B for ; Thu, 21 Jul 2016 15:14:51 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id D6F1C160A6D; Thu, 21 Jul 2016 13:14:51 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 05807160A68 for ; Thu, 21 Jul 2016 15:14:50 +0200 (CEST) Received: (qmail 22564 invoked by uid 500); 21 Jul 2016 13:14:50 -0000 Mailing-List: contact commits-help@celix.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@celix.apache.org Delivered-To: mailing list commits@celix.apache.org Received: (qmail 22555 invoked by uid 99); 21 Jul 2016 13:14:50 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 21 Jul 2016 13:14:50 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 0B97DE1101; Thu, 21 Jul 2016 13:14:50 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: pnoltes@apache.org To: commits@celix.apache.org Message-Id: <1d9154f7e5444eb2936c6298c22b27a9@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: celix git commit: CELIX-368: Adds readme for C++ Dependency Manager Date: Thu, 21 Jul 2016 13:14:50 +0000 (UTC) archived-at: Thu, 21 Jul 2016 13:14:52 -0000 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 Authored: Thu Jul 21 15:14:22 2016 +0200 Committer: Pepijn Noltes 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