CELIX-368: Upates the documentation. specifically the getting started guide. Fixes some install issue with the C++ dep man
Project: http://git-wip-us.apache.org/repos/asf/celix/repo Commit: http://git-wip-us.apache.org/repos/asf/celix/commit/3c0bcf36 Tree: http://git-wip-us.apache.org/repos/asf/celix/tree/3c0bcf36 Diff: http://git-wip-us.apache.org/repos/asf/celix/diff/3c0bcf36 Branch: refs/heads/release/celix-2.0.0 Commit: 3c0bcf369127ccc30ac41d717f2f0797742d3e82 Parents: 7766b2a Author: Pepijn Noltes <pepijnnol...@gmail.com> Authored: Tue Sep 27 21:10:26 2016 +0200 Committer: Pepijn Noltes <pepijnnol...@gmail.com> Committed: Tue Sep 27 21:10:26 2016 +0200 ---------------------------------------------------------------------- cmake/FindCELIX.cmake | 29 +- dependency_manager_cxx/CMakeLists.txt | 15 +- .../include/celix/dm/DmActivator.h | 12 +- dependency_manager_cxx/include/celix/dm/types.h | 2 +- .../src/dm_activator_base_cxx.cc | 4 +- documents/best_practices/readme.md | 585 ------------------- documents/building/readme.md | 4 +- .../getting_started/creating_a_simple_bundle.md | 306 ++++++++++ documents/getting_started/readme.md | 218 +------ .../getting_started/using_services_with_c.md | 585 +++++++++++++++++++ documents/intro/readme.md | 1 - .../phase1/include/Phase1Activator.h | 4 +- .../phase1/src/Phase1Activator.cc | 4 +- .../phase2/include/Phase2Activator.h | 4 +- .../phase2a/src/Phase2aActivator.cc | 4 +- .../phase2b/src/Phase2bActivator.cc | 4 +- .../phase3/include/Phase3Activator.h | 2 +- .../phase3/src/Phase3Activator.cc | 2 +- .../include/Phase3LockingActivator.h | 2 +- .../src/Phase3LockingActivator.cc | 2 +- 20 files changed, 947 insertions(+), 842 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/cmake/FindCELIX.cmake ---------------------------------------------------------------------- diff --git a/cmake/FindCELIX.cmake b/cmake/FindCELIX.cmake index b2789df..1ddb1ca 100644 --- a/cmake/FindCELIX.cmake +++ b/cmake/FindCELIX.cmake @@ -24,7 +24,10 @@ # CELIX_INCLUDE_DIRS - The Apache Celix include directories # CELIX_LIBRARIES - The libraries needed to use Apache Celix # CELIX_LAUNCHER - The path to the celix launcher +# # CELIX_BUNDLES_DIR - The path where the Celix provided bundles are installed +# CELIX_DM_STATIC_LIB - The Celix Dependency Manager static library +# CELIX_DM_CXX_STATIC_LIB - The Celix C++ Dependency Manager static library set(CELIX_DIR_FROM_FINDCELIX "${CMAKE_CURRENT_LIST_DIR}/../../../..") @@ -64,18 +67,36 @@ find_path(CELIX_BUNDLES_DIR shell.zip PATHS ${CELIX_DIR_FROM_FINDCELIX} $ENV{CELIX_DIR} ${CELIX_DIR} /usr /usr/local PATH_SUFFIXES share/celix/bundles ) - +find_library(CELIX_DM_STATIC_LIB NAMES dependency_manager_static + PATHS ${CELIX_DIR_FROM_FINDCELIX} $ENV{CELIX_DIR} ${CELIX_DIR} /usr /usr/local + PATH_SUFFIXES lib lib64 +) +if (CELIX_DM_STATIC_LIB) + set(CELIX_DM_INCLUDE_DIR ${CELIX_INCLUDE_DIR}/dependency_manager) +else() + set(CELIX_DM_INCLUDE_DIR ) +endif() + +find_library(CELIX_DM_CXX_STATIC_LIB NAMES dependency_manager_cxx_static + PATHS ${CELIX_DIR_FROM_FINDCELIX} $ENV{CELIX_DIR} ${CELIX_DIR} /usr /usr/local + PATH_SUFFIXES lib lib64 +) +if (CELIX_DM_CXX_STATIC_LIB) + set(CELIX_DM_CXX_INCLUDE_DIR ${CELIX_INCLUDE_DIR}/dependency_manager_cxx) +else() + set(CELIX_DM_CXX_INCLUDE_DIR ) +endif() include(FindPackageHandleStandardArgs) # handle the QUIETLY and REQUIRED arguments and set CELIX_FOUND to TRUE # if all listed variables are TRUE find_package_handle_standard_args(CELIX DEFAULT_MSG - CELIX_FRAMEWORK_LIBRARY CELIX_UTILS_LIBRARY CELIX_INCLUDE_DIR CELIX_LAUNCHER CELIX_CMAKECELIX_FILE) + CELIX_FRAMEWORK_LIBRARY CELIX_UTILS_LIBRARY CELIX_DFI_LIBRARY CELIX_DM_STATIC_LIB CELIX_DM_CXX_STATIC_LIB CELIX_INCLUDE_DIR CELIX_LAUNCHER CELIX_CMAKECELIX_FILE) mark_as_advanced(CELIX_INCLUDE_DIR CELIX_FRAMEWORK_LIBRARY CELIX_UTILS_LIBRARY CELIX_LAUNCHER CELIX_CMAKECELIX_FILE) if(CELIX_FOUND) - set(CELIX_LIBRARIES ${CELIX_FRAMEWORK_LIBRARY} ${CELIX_UTILS_LIBRARY}) - set(CELIX_INCLUDE_DIRS ${CELIX_INCLUDE_DIR}) + set(CELIX_LIBRARIES ${CELIX_FRAMEWORK_LIBRARY} ${CELIX_UTILS_LIBRARY} ${CELIX_DFI_LIBRARY}) + set(CELIX_INCLUDE_DIRS ${CELIX_INCLUDE_DIR} ${CELIX_DM_INCLUDE_DIR} ${CELIX_DM_CXX_INCLUDE_DIR}) include(${CELIX_CMAKECELIX_FILE}) endif() http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/dependency_manager_cxx/CMakeLists.txt ---------------------------------------------------------------------- diff --git a/dependency_manager_cxx/CMakeLists.txt b/dependency_manager_cxx/CMakeLists.txt index c2d8076..8dc595c 100644 --- a/dependency_manager_cxx/CMakeLists.txt +++ b/dependency_manager_cxx/CMakeLists.txt @@ -54,22 +54,9 @@ if (DEPENDENCY_MANAGER_CXX) #set_target_properties(dependency_manager_cxx_static PROPERTIES SOVERSION 1) target_link_libraries(dependency_manager_cxx_static celix_framework) - #NOTE need to install dep man headers? or depend on install of dependency manager? - install( - FILES - ${DM_DIR}/public/include/dm_activator.h - ${DM_DIR}/public/include/dm_component.h - ${DM_DIR}/public/include/dm_dependency_manager.h - ${DM_DIR}/public/include/dm_service_dependency.h - ${DM_DIR}/public/include/dm_info.h - DESTINATION - include/celix/dependency_manager_cxx - COMPONENT - dependency_manager_cxx - ) install( DIRECTORY - include + include/celix DESTINATION include/celix/dependency_manager_cxx COMPONENT http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/dependency_manager_cxx/include/celix/dm/DmActivator.h ---------------------------------------------------------------------- diff --git a/dependency_manager_cxx/include/celix/dm/DmActivator.h b/dependency_manager_cxx/include/celix/dm/DmActivator.h index e1207df..57f2f97 100644 --- a/dependency_manager_cxx/include/celix/dm/DmActivator.h +++ b/dependency_manager_cxx/include/celix/dm/DmActivator.h @@ -26,24 +26,26 @@ namespace celix { namespace dm { class DmActivator { protected: - DependencyManager& manager; - DmActivator(DependencyManager& mng) : manager(mng) {} + DependencyManager& depMng; + DmActivator(DependencyManager& mng) : depMng(mng) {} public: ~DmActivator() = default; + DependencyManager& manager() const { return this->depMng; } + /** * The init of the DM Activator. Should be overridden by the bundle specific DM activator. * * @param manager A reference to the Dependency Manager */ - virtual void init(DependencyManager& manager) {}; + virtual void init() {}; /** * The init of the DM Activator. Can be overridden by the bundle specific DM activator. * * @param manager A reference to the Dependency Manager */ - virtual void deinit(DependencyManager& manager) {}; + virtual void deinit() {}; /** * Creates and adds a new DM Component for a component of type T. @@ -53,7 +55,7 @@ namespace celix { namespace dm { * @return Returns a reference to the DM Component */ template< class T> - Component<T>& createComponent(std::shared_ptr<T> inst = std::shared_ptr<T>{nullptr}) { return manager.createComponent<T>(inst); } + Component<T>& createComponent(std::shared_ptr<T> inst = std::shared_ptr<T>{nullptr}) { return depMng.createComponent<T>(inst); } /** * The static method to create a new DM activator. http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/dependency_manager_cxx/include/celix/dm/types.h ---------------------------------------------------------------------- diff --git a/dependency_manager_cxx/include/celix/dm/types.h b/dependency_manager_cxx/include/celix/dm/types.h index bafeca4..9971de7 100644 --- a/dependency_manager_cxx/include/celix/dm/types.h +++ b/dependency_manager_cxx/include/celix/dm/types.h @@ -53,7 +53,7 @@ namespace celix { namespace dm { std::string result; #ifdef __GXX_RTTI - result = typeid(I); + result = typeid(INTERFACE_TYPENAME).name(); int status = 0; char* demangled_name {abi::__cxa_demangle(result.c_str(), NULL, NULL, &status)}; if(status == 0) { http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/dependency_manager_cxx/src/dm_activator_base_cxx.cc ---------------------------------------------------------------------- diff --git a/dependency_manager_cxx/src/dm_activator_base_cxx.cc b/dependency_manager_cxx/src/dm_activator_base_cxx.cc index f895d0e..f2ef89a 100644 --- a/dependency_manager_cxx/src/dm_activator_base_cxx.cc +++ b/dependency_manager_cxx/src/dm_activator_base_cxx.cc @@ -82,7 +82,7 @@ celix_status_t bundleActivator_start(void *userData, bundle_context_pt context) return CELIX_ILLEGAL_STATE; } - act->activator->init(*act->manager); + act->activator->init(); act->manager->start(); if (status == CELIX_SUCCESS) { @@ -120,7 +120,7 @@ celix_status_t bundleActivator_destroy(void *userData, bundle_context_pt context return CELIX_ILLEGAL_STATE; } - act->activator->deinit(*act->manager); + act->activator->deinit(); act->manager->stop(); delete act; http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/best_practices/readme.md ---------------------------------------------------------------------- diff --git a/documents/best_practices/readme.md b/documents/best_practices/readme.md deleted file mode 100644 index b098f48..0000000 --- a/documents/best_practices/readme.md +++ /dev/null @@ -1,585 +0,0 @@ -#Apache Celix - Best Practices - -## Intro - -This example should give a best practice approach for providing and using service with Apache Celix. - -## Services - -To start-of, services in Celix are just a pointer to a memory location registered in the service registry using a name and an optional set of key/value pairs. - -By convention use the following service layout: - -```C -//example.h -#ifndef EXAMPLE_H_ -#define EXAMPLE_H_ - -#define EXAMPLE_NAME "org.example" -#define EXAMPLE_VERSION "1.0.0" -#define EXAMPLE_CONSUMER_RANGE "[1.0.0,2.0.0)" - - -struct example_struct { - void *handle; - int (*method)(void *handle, int arg1, double arg2, double *result); -} ; - -typedef struct example_struct example_t; - -#endif /* EXAMPLE_H_ */ - -``` - - -For a Celix service a service name, service version and service consumer range should be declared. -This is explicitly done with macros to prevent symbols so to that no linking dependencies are introduced. - -Then the actual struct for the service needs to be declared. -The first element of the service struct should be a handle which can be used to store the service context, as convention we keep this pointer a void pointer to explicitly make it opaque. -Note that also an opaque struct could be used (e.g a declared but not defined struct), but this can become problematic concerning components registering multiple services. -In that case explicit cast are needed to prevent warning and this can be confusing for the To prevent that issues void pointers are preferred. - -The rest of the element should be function pointers, which by convention should return an celix_status_t or int (which is technically the same). -The return value is used as a way of handling errors and is also needed to be able to make remote services (e.g. to be able to handle remote exceptions). - -The first argument of a service function should be the service handle and if there is a result the last argument should be a output parameter (either pre allocated (e.g. double *) or not (e.g. double **)). -It is also possible to create typedef of the pointer to the service struct (e.g. typedef struct example_service *example_service_pt), but this is not needed. -If you do not create typedefs with pointers it is easier to include service struct in an parent struct (without memory allocation) and also make it's possible to use the const on the struct instead of the pointer. - -### Semantic Versioning - -For versioning, semantic versioning should be used. - -A backward incompatible change should lead to a major version increase (e.g. 1.0.0 -> 2.0.0). -For a C Service change that are incompatible are: - -- Removing a function -- Adding a function to before any other function -- Moving a function to an other location in the service struct -- Changing the signature of a function -- Changing the semantics of a argument (e.g. changing range input from "range in kilometer" to "range in meters") - -A backwards compatible change which extend the functionality should lead to a minor version increase (e.g. 1.0.0 -> 1.1.0). -Changes considered backwards compatible which extend the functionality are: - -- Adding a function to the back of the service struct - -A backwards compatible change which does not extend the functionality should lead to a micro version increase (e.g. 1.0.0 -> 1.0.1). -Changes considered backwards compatible which does not extend the functionaility are: - -- Changes in the documentation -- Renaming of arguments - - -## Components - -Component should use the ADT principle (see [ADT in C](http://inst.eecs.berkeley.edu/~selfpace/studyguide/9C.sg/Output/ADTs.in.C.html)). - -Components should have a `<cmpName>_create` and `<cmpName>_destroy` function. -Components can have a `<cmpName>_start` and `<cmpName>_stop` function to start/stop threads or invoke functionality needed a fully created component. -The start function will only be called if all required service are available and the stop function will be called when some required are going or if the component needs to be stopped. - -Components can also have a `<cmpName>_init` and `<cmpName>_deinit` function which will be called before and after respectively the start and stop function. -The init function can be used to add additional (even required) service dependencies. -The use case for init/deinit component functions are exceptional. - - -## Code Examples - -The next code block contains some code examples of components to indicate how to handle service dependencies, how to specify providing services and how to cope with locking/synchronizing. -The complete example can be found [here](../../examples/best_practice_example). - -The error checking is very minimal in these example to keep the focus on how to interact with services and how to deal with errors in C / Celix. - - -### Bar example - -The bar example is a simple component providing the `example` service. - -```C -//bar.h -#ifndef BAR_H_ -#define BAR_H_ - -#include "example.h" - -typedef struct bar_struct bar_t; - -bar_t* bar_create(void); -void bar_destroy(bar_t *self); - -int bar_method(bar_t *self, int arg1, double arg2, double *out); - -#endif //BAR_H_ -``` - -```C -//bar.c -#define OK 0 -#define ERROR 1 - -struct bar_struct { - double prefValue; -}; - -bar_t* bar_create(void) { - bar_t *self = calloc(1, sizeof(*self)); - if (self != NULL) { - self->prefValue = 42; - } else { - //log error - } - return self; -}; - -void bar_destroy(bar_t *self) { - free(self); -} - -int bar_method(bar_t *self, int arg1, double arg2, double *out) { - double update = (self->prefValue + arg1) * arg2; - self->prefValue = update; - *out = update; - return OK; -} -``` - -```C -//bar_activator.c -#include "dm_activator.h" -#include "bar.h" - -#include <stdlib.h> - -struct activator { - bar_t *bar; - example_t exampleService; -}; - -celix_status_t dm_create(bundle_context_pt context, void **userData) { - celix_status_t status = CELIX_SUCCESS; - struct activator *act = calloc(1, sizeof(*act)); - if (act != NULL) { - - act->bar = bar_create(); - act->exampleService.handle = act->bar; - act->exampleService.method = (void*) bar_method; - - if (act->bar != NULL) { - *userData = act; - } else { - free(act); - } - } else { - status = CELIX_ENOMEM; - } - return status; -} - -celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - - dm_component_pt cmp = NULL; - component_create(context, "BAR", &cmp); - component_setImplementation(cmp, activator->bar); - component_addInterface(cmp, EXAMPLE_NAME, EXAMPLE_VERSION, &activator->exampleService, NULL); - - dependencyManager_add(manager, cmp); - return status; -} - -celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - bar_destroy(activator->bar); - free(activator); - return status; -}; -``` - -### Foo1 example - -The Foo1 example shows how add a service dependency, implement the callback, invoke a service and how to protect the usage of service with use of a mutex. - -```C -//foo1.h -#ifndef FOO1_H_ -#define FOO1_H_ - -#include "example.h" - -typedef struct foo1_struct foo1_t; - -foo1_t* foo1_create(void); -void foo1_destroy(foo1_t *self); - -int foo1_start(foo1_t *self); -int foo1_stop(foo1_t *self); - -int foo1_setExample(foo1_t *self, const example_t *example); - - -#endif //FOO1_H_ -``` - -```C -//foo1.c -#include "foo1.h" - -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> -#include <string.h> -#include <signal.h> -#include <stdbool.h> -#include <pthread.h> -#include <assert.h> - - -#define OK 0 -#define ERROR 1 - -static void* foo1_thread(void*); - -struct foo1_struct { - const example_t *example; - pthread_mutex_t mutex; //protecting example - pthread_t thread; - bool running; -}; - -foo1_t* foo1_create(void) { - foo1_t *self = calloc(1, sizeof(*self)); - if (self != NULL) { - pthread_mutex_init(&self->mutex, NULL); - self->running = false; - } else { - //log error - } - return self; -}; - -void foo1_destroy(foo1_t *self) { - assert(!self->running); - pthread_mutex_destroy(&self->mutex); - free(self); -} - -int foo1_start(foo1_t *self) { - self->running = true; - pthread_create(&self->thread, NULL, foo1_thread, self); - return OK; -} - -int foo1_stop(foo1_t *self) { - self->running = false; - pthread_kill(self->thread, SIGUSR1); - pthread_join(self->thread, NULL); - return OK; -} - -int foo1_setExample(foo1_t *self, const example_t *example) { - pthread_mutex_lock(&self->mutex); - self->example = example; //NOTE could be NULL if req is not mandatory - pthread_mutex_unlock(&self->mutex); - return OK; -} - -static void* foo1_thread(void *userdata) { - foo1_t *self = userdata; - double result; - int rc; - while (self->running) { - pthread_mutex_lock(&self->mutex); - if (self->example != NULL) { - rc = self->example->method(self->example->handle, 1, 2.0, &result); - if (rc == 0) { - printf("Result is %f\n", result); - } else { - printf("Error invoking method for example\n"); - } - } - pthread_mutex_unlock(&self->mutex); - usleep(10000000); - } - return NULL; -} -``` - -```C -//foo1_activator.c -#include "dm_activator.h" -#include "foo1.h" - -#include <stdlib.h> - -struct activator { - foo1_t *foo; -}; - -celix_status_t dm_create(bundle_context_pt context, void **userData) { - celix_status_t status = CELIX_SUCCESS; - struct activator *act = calloc(1, sizeof(*act)); - if (act != NULL) { - act->foo = foo1_create(); - if (act->foo != NULL) { - *userData = act; - } else { - free(act); - } - } else { - status = CELIX_ENOMEM; - } - return status; -} - -celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - - dm_component_pt cmp = NULL; - component_create(context, "FOO1", &cmp); - component_setImplementation(cmp, activator->foo); - - /* - With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component - with type foo1_t* - */ - component_setCallbacksSafe(cmp, foo1_t*, NULL, foo1_start, foo1_stop, NULL); - - dm_service_dependency_pt dep = NULL; - serviceDependency_create(&dep); - serviceDependency_setRequired(dep, true); - serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL); - serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING); - - /* - With the serviceDependency_setCallbacksSafe we register callbacks when a service - is added and about to be removed for the component type foo1_t* and service type example_t*. - - We should protect the usage of the - service because after removal of the service the memory location of that service - could be freed - */ - serviceDependency_setCallbacksSafe(dep, foo1_t*, const example_t*, foo1_setExample, NULL, NULL, NULL, NULL); - component_addServiceDependency(cmp, dep); - - dependencyManager_add(manager, cmp); - - return status; -} - -celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - foo1_destroy(activator->foo); - free(activator); - return status; -}; - -``` - -### Foo2 example - -The Foo2 example shows how to cope with multiple services and how to remove the need for locking by ensuring only access to the services and the services container by a single thread. - -```C -//foo2.h -#ifndef FOO2_H_ -#define FOO2_H_ - -#include "example.h" - -typedef struct foo2_struct foo2_t; - -foo2_t* foo2_create(void); -void foo2_destroy(foo2_t *self); - -int foo2_start(foo2_t *self); -int foo2_stop(foo2_t *self); - -int foo2_addExample(foo2_t *self, const example_t *example); -int foo2_removeExample(foo2_t *self, const example_t *example); - -#endif //FOO2_H_ -``` - -```C -//foo2.c -#include "foo2.h" - -#include "array_list.h" - -#include <stdio.h> -#include <stdlib.h> -#include <unistd.h> -#include <string.h> -#include <signal.h> -#include <stdbool.h> -#include <pthread.h> -#include <assert.h> - - -#define OK 0 -#define ERROR 1 - -static void* foo2_thread(void*); - -struct foo2_struct { - array_list_pt examples; - pthread_t thread; - bool running; -}; - -foo2_t* foo2_create(void) { - foo2_t *self = calloc(1, sizeof(*self)); - if (self != NULL) { - self->examples = NULL; - arrayList_create(&self->examples); - self->running = false; - } else { - //log error - } - return self; -}; - -void foo2_destroy(foo2_t *self) { - assert(!self->running); - arrayList_destroy(self->examples); - free(self); -} - -int foo2_start(foo2_t *self) { - self->running = true; - pthread_create(&self->thread, NULL, foo2_thread, self); - return OK; -} - -int foo2_stop(foo2_t *self) { - self->running = false; - pthread_kill(self->thread, SIGUSR1); - pthread_join(self->thread, NULL); - return OK; -} - -int foo2_addExample(foo2_t *self, const example_t *example) { - //NOTE foo2 is suspended -> thread is not running -> safe to update - int status = OK; - status = arrayList_add(self->examples, (void *)example); - return status; -} - -int foo2_removeExample(foo2_t *self, const example_t *example) { - //NOTE foo2 is suspended -> thread is not running -> safe to update - int status = OK; - status = arrayList_removeElement(self->examples, (void*)example); - return status; -} - -static void* foo2_thread(void *userdata) { - foo2_t *self = userdata; - double result; - int rc; - while (self->running) { - unsigned int size = arrayList_size(self->examples); - int i; - for (i = 0; i < size; i += 1) { - const example_t* example = arrayList_get(self->examples, i); - rc = example->method(example->handle, 1, 2.0, &result); - if (rc == 0) { - printf("Result is %f\n", result); - } else { - printf("Error invoking method for example\n"); - } - } - usleep(10000000); - } - return NULL; - -``` - -```C -//foo2_activator.c -#include "dm_activator.h" -#include "foo2.h" - -#include <stdlib.h> - -struct activator { - foo2_t *foo; -}; - -celix_status_t dm_create(bundle_context_pt context, void **userData) { - celix_status_t status = CELIX_SUCCESS; - struct activator *act = calloc(1, sizeof(*act)); - if (act != NULL) { - act->foo = foo2_create(); - if (act->foo != NULL) { - *userData = act; - } else { - free(act); - } - } else { - status = CELIX_ENOMEM; - } - return status; -} - -celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - - dm_component_pt cmp = NULL; - component_create(context, "FOO2", &cmp); - component_setImplementation(cmp, activator->foo); - - /* - With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component - with type foo1_t* - */ - component_setCallbacksSafe(cmp, foo2_t*, NULL, foo2_start, foo2_stop, NULL); - - dm_service_dependency_pt dep = NULL; - serviceDependency_create(&dep); - serviceDependency_setRequired(dep, false); - serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL); - serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND); - - /* - With the serviceDependency_setCallbacksSafe we register callbacks when a service - is added and about to be removed for the component type foo1_t* and service type example_t*. - - We should protect the usage of the - service because after removal of the service the memory location of that service - could be freed - */ - serviceDependency_setCallbacksSafe(dep, foo2_t*, const example_t*, NULL, foo2_addExample, foo2_removeExample, NULL, NULL); - component_addServiceDependency(cmp, dep); - - dependencyManager_add(manager, cmp); - - return status; -} - -celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { - celix_status_t status = CELIX_SUCCESS; - struct activator *activator = userData; - foo2_destroy(activator->foo); - free(activator); - return status; -}; -``` - -## Locking and Suspending - -As you may notice, the Foo1 example uses locks. -In principle, locking is necessary in order to ensure coherence in case service dependencies are removed/added/changed; on the other hands, locking increases latency and, when misused, can lead to poor performance. -For this reason, the serviceDependecy interface gives the possibility to choose between a locking and suspend (a non-locking) strategy through the serviceDependency_setStrategy function, as is used in the Foo2 example. - -The locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING` notifies the component in case the dependencies' set changes (e.g. a dependency is added/removed): the component is responsible for protecting via locks the dependencies' list and check (always under lock) if the service he's depending on is still available. -The suspend or non-locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` (default when no strategy is explicitly set) reliefs the programmer from dealing with service dependencies' consistency issues: in case this strategy is adopted, the component is stopped and restarted (i.e. temporarily suspended) upon service dependencies' changes. - -The suspend strategy has the advantage of reducing locks' usage: of course, suspending the component has its own overhead (e.g. stopping and restarting threads), but this overhead is "paid" only in case of changes in service dependencies, while the locking overhead is always paid. - http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/building/readme.md ---------------------------------------------------------------------- diff --git a/documents/building/readme.md b/documents/building/readme.md index 282eec1..a074e4e 100644 --- a/documents/building/readme.md +++ b/documents/building/readme.md @@ -99,8 +99,8 @@ ninja ``` ##Editing Build options -With use of CMake Apache Celix makes it possible to edit build options. This enabled users to configure a install location and selecting additional bundles. -To edit the options use ccmake or cmake-gui. For cmake-gui an additional package install can be neccesary (Fedora: `dnf install cmake-gui`). +With use of CMake, Apache Celix makes it possible to edit build options. This enabled users, among other options, to configure a install location and select additional bundles. +To edit the options use ccmake or cmake-gui. For cmake-gui an additional package install can be necessary (Fedora: `dnf install cmake-gui`). ```bash cd ${WS}/celix/build http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/getting_started/creating_a_simple_bundle.md ---------------------------------------------------------------------- diff --git a/documents/getting_started/creating_a_simple_bundle.md b/documents/getting_started/creating_a_simple_bundle.md new file mode 100644 index 0000000..5ea1c40 --- /dev/null +++ b/documents/getting_started/creating_a_simple_bundle.md @@ -0,0 +1,306 @@ +#Apache Celix - Getting Started Guide: Creating a Simple Bundle + +##Intro +This page is intended for first time users of Apache Celix. It should guide you through building & installing Apache Celix, setting up a new project, creating your first bundle, setting up the project for use with Eclipse project and finally running and debugging your bundle directly from eclipse workspace. + +If there are any uncertainties or question, don't hesitate to ask your questions in the [Apache Celix mailing](https://celix.apache.org/support/mailinglist.html). + +##Prerequisite +Some experience with a command line interface (xterm) is expected to be able to follow this guide. + +##Building and Installing +For Apache Celix see [Building And Installing](../building/readme.md) + +##Installing Eclipse CDT +Download the latest eclipse CDT at [http://www.eclipse.org](http://www.eclipse.org) and install it on your system. For more information on how the install eclipse on your system consult the eclipse documentation. For this getting started guide the luna version of eclipse was used ([linux](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-linux-gtk-x86_64.tar.gz) [mac](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-macosx-cocoa-x86_64.tar.gz)). + +##Apache Celix Bundle project +Now that Apache Celix and Eclipse is installed, we are ready to create a new Apache Celix Bundle project. In this project cmake will be create a singe hello world bundle with a deployment configuration for testing the bundle. + +To setup of the project, first create a new project dir to work in: + +```bash +#Create a new workspace to work in, e.g: +mkdir ${HOME}/workspace +export WS=${HOME}/workspace + +mkdir ${WS}/myproject +cd ${WS}/myproject +``` + +Then create a CMakeLists.txt file - the makefile variant of CMake -in project root directory: + +```cmake +#${WS}/myproject/CMakeLists.txt + +#Part 1. setup project +cmake_minimum_required(VERSION 3.4) +project(myproject C CXX) + +#Part 2. setup compilers +SET(CMAKE_C_FLAGS "-D_GNU_SOURCE -std=gnu99 -Wall -Werror -fPIC ${CMAKE_C_FLAGS}") +SET(CMAKE_C_FLAGS_DEBUG "-g -DDEBUG") +SET(CMAKE_CXX_FLAGS "-std=c++11 ${CMAKE_CXX_FLAGS}") +SET(CMAKE_CXX_FLAGS_DEBUG "-g -DDEBUG") + +#Part 3. Setup Celix cmake files, include paths, libraries and library paths +#Note. If celix is not installed in /usr/local dir, change the location accordingly. +set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/local/share/celix/cmake/modules") +find_package(CELIX REQUIRED) +include_directories(${CELIX_INCLUDE_DIRS}) + +#Part 4. Choose C, C++ or both +add_subdirectory(bundles/hello_world) #C +add_subdirectory(bundles/HelloWorld) #C++ +``` + +This CMakeLists.txt file, sets up the following: + +* Part 1 + * The minimum cmake version required. + * The project name + * The type of source files to expect, in this case C and C++. +* Part 2 + * Setup the compilers. c99 for C and C++11 for C++ +* Part 3 + * The Celix package should be searched, configured and that the Celix package is required. + * For all build targets in this CMakeLists.txt file or any sub directory CMakeLists.txt files the Apache Celix headers directory should be included. +* Part 4 + * The CMakelists.txt file in the subdirectory bundles/hello_world and/or bundles/HelloWorld should also be processed. + + +It is a good practice to create a separate CMakeLists.txt file for every bundle you want to build. For the hello_world bundle a CMakeLists.txt file should be created in the bundles/hello_world sub directory. + +Create the sub directory: + +```CMake +#Create directory structure for the hello_world bundles +cd ${WS}/myproject +mkdir -p bundles/hello_world/private/src +mkdir -p bundles/HelloWorld/private/src +mkdir -p bundles/HelloWorld/private/include +``` + + +And add the following CMakeLists.txt file for the C Bundle: + +```CMake +#${WS}/myproject/bundles/hello_world/CMakeLists.txt + +add_bundle(hello_world + VERSION 1.0.0 + SOURCES + private/src/hello_world_activator.c +) + +if(APPLE) + target_link_libraries(hello_world ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_STATIC_LIB}) +else() + target_link_libraries(hello_world -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_STATIC_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES}) +endif() +``` + +And/or the following CMakeLists.txt for the C++ bundle: + +```CMake +#${WS}/myproject/bundles/HelloWorld/CMakeLists.txt + +include_directories( + private/include +) + +add_bundle(HelloWorld + VERSION 1.0.0 + SOURCES + private/src/HelloWorldActivator.cc +) + +IF(APPLE) + target_link_libraries(HelloWorld ${CELIX_LIBRARIES} -Wl,-all_load ${CELIX_DM_CXX_STATIC_LIB}) +else() + target_link_libraries(HelloWorld -Wl,--no-undefined -Wl,--whole-archive ${CELIX_DM_CXX_STATIC_LIB} -Wl,--no-whole-archive ${CELIX_LIBRARIES}) +endif() +``` + +These CMakeLists.txt files declare that the bundles should be build based on the build result (shared library) of the declared sources (in this case the private/src/hello_world_activator.c or private/src/HelloWorldActivator.cc source). +The add_bundle function is an Apache Celix specific CMake extension. +The library used for the bundle will also be linked against the dependency manager static library. + + +The Celix framework will install the bundle, load the bundle shared library and call the bundle activator entry symbols. These entries need to be programmed by the user. +Note that in these examples we use the dependency manager libraries (C and C++ version) instead of developing a "naked" bundle activator; The dependency manager uses a higher abstraction and is more simple to understand and maintain. + +The C Bundle Activator: +```C +//${WS}/myproject/bundles/hello_world/private/src/hello_world_activator.c +#include <stdlib.h> +#include <stdio.h> + +#include "dm_activator.h" + + +struct userData { + char * word; +}; + +celix_status_t dm_create(bundle_context_pt context, void **out) { + celix_status_t status = CELIX_SUCCESS; + struct userData* result = calloc(1, sizeof(*result)); + if (result != NULL) { + result->word = "C World"; + *out = result; + } else { + status = CELIX_START_ERROR; + } + return status; +} + +celix_status_t dm_init(void* userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + struct userData* data = (struct userData *) userData; + printf("Hello %s\n", data->word); + return CELIX_SUCCESS; +} + +celix_status_t dm_destroy(void* userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + free(userData); + return CELIX_SUCCESS; +} +``` + +The C++ Bundle Activator (header + source): +```C++ +//${WS}/myproject/bundles/HelloWorld/private/include/HelloWorldActivator.h +#ifndef HELLOWORLDACTIVATOR_H_ +#define HELLOWORLDACTIVATOR_H_ + +#include "celix/dm/DmActivator.h" + +using namespace celix::dm; + +class HelloWorldActivator : public DmActivator { +private: + const std::string word {"C++ World"}; +public: + HelloWorldActivator(DependencyManager& mng) : DmActivator {mng} {} + virtual void init(); + virtual void deinit(); +}; + +#endif //HELLOWORLDACTIVATOR_H_ + +//${WS}/myproject/bundles/HelloWorld/private/src/HelloWorldActivator.cc +#include "HelloWorldActivator.h" +#include <iostream> + +using namespace celix::dm; + +DmActivator* DmActivator::create(DependencyManager& mng) { + return new HelloWorldActivator(mng); +} + +void HelloWorldActivator::init() { + std::cout << "Hello " << this->word << "\n"; +} + +void HelloWorldActivator::deinit() { + //nothing to do +} +``` + +###Building +One of the highly recommended features of CMake is the ability to do out of source builds, the benefit is that all of the build results will go in a separate directory without cluttering the (source) project. +CMake also needs to able to find the cmake files Celix provides. This can be achieved by providing a CMAKE_MODULE_PATH variable (or setting the CMAKE_MODULE_PATH in the top level CMakeLists.txt). +For this example it is assumed that Celix in installed in `/usr/local`. +To create the build directory and build the project execute the following commands: + + +```bash +cd ${WS} +mkdir myproject/build +cd myproject/build +cmake .. +make all +#Or +#cmake -G Ninja .. +#ninja +``` + +Hopefully you will some some build results scrolling over the screen and actual build results in the build directory. There should be a hello_world.zip in the bundles/hello_world directory, this the actual bundle. But a bundle on its own has no real value, so lets setup a deployment and run the Apache Celix framwork with this bundle. + +###Running + +To create a deployment for the hello world bundles two things are needed: + +1. Add a `add_deploy` statement in the `CMakeLists.txt` file declaring what to deploy and under which name. + +```CMake +#${WS}/myproject/CMakeLists.txt +add_deploy(hello + BUNDLES + ${CELIX_BUNDLES_DIR}/shell.zip + ${CELIX_BUNDLES_DIR}/shell_tui.zip + ${CELIX_BUNDLES_DIR}/dm_shell.zip + hello_world #C bundle + HelloWorld #C++ bundle +) +``` + +Rerun make again form the build project. the make files generated by CMake will ensure cmake is run it again to update the actual make files. + +```bash +cd ${WS}/myproject-build +make -j +#or +#ninja +``` + +Now a deploy directory myproject should be available in the deploy directory. This directory contains - among other files - the run.sh script. This can be used to run the Apache Celix framework with the declared bundles from the deploy.cmake. + +```bash +cd ${WS}/myproject-build/deploy/hello +. ./release.sh +celix +#or ./hello +``` + +The hello_world bundle should be started with the famous "Hello World" text printed twice from the C and C++ bundle. The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for querying the installed bundles, listing all known shell command, showing the help of a specific command and stopping a specific bundle (note that bundle 0 is the framework "bundle"): + +``` +lb +help +help inspect +stop 0 +``` + +##Apache Celix Bundle Project in Eclipse + +A nice feature of CMake is the ability to generate Eclipse project files, with this feature bundles can also be developed with use of Eclipse. This should help speed up the development process. +To get started change directory to the build directory and generate a eclipse project file. + + cd ${WS}/myproject-build + cmake -G "Eclipse CDT4 - Unix Makefiles" . + +Startup the Eclipse EDI and a chose the `${WS}` + + + +Import the project with existing project. + + + +To build the project, use Project->Build All. To run or debug from Eclipse navigate to the myproject deploy directory and right click on the 'myproject-deploy.launch' file. And select Run As or Debug As to run or debug the bundle. + + + +##Next + +The idea behind service oriented programming is that functionality is provided and used by abstract service, which hide implementation details. +For a guide how to provide and use services see + +* [Apache Celix - Getting Started Guide: Using Services with C](using_services_with_c.md) +* [Apache Celix - Getting Started Guide: Using services with C++](using_services_with_cxx.md) + + + + + http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/getting_started/readme.md ---------------------------------------------------------------------- diff --git a/documents/getting_started/readme.md b/documents/getting_started/readme.md index 7b82180..9c391e9 100644 --- a/documents/getting_started/readme.md +++ b/documents/getting_started/readme.md @@ -1,216 +1,6 @@ #Apache Celix - Getting Started Guide -##Intro -This page is intended for first time users of Apache Celix. It should guide you through building & installing Apache Celix, setting up a new project, creating your first bundle, setting up the project for use with Eclipse project and finally running and debugging your bundle directly from eclipse workspace. - -If there are any uncertainties or question, don't hesitate to ask your questions in the [Apache Celix mailing](https://celix.apache.org/support/mailinglist.html). - -##Prerequisite -Some experience with a command line interface (xterm) is expected to be able to follow this guide. - -##Building and Installing -For Apache Celix see [Building And Installing](../building/readme.md) - -##Installing Eclipse CDT -Download the latest eclipse CDT at [http://www.eclipse.org](http://www.eclipse.org) and install it on your system. For more information on how the install eclipse on your system consult the eclipse documentation. For this getting started guide the luna version of eclipse was used ([linux](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-linux-gtk-x86_64.tar.gz) [mac](http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/luna/R/eclipse-cpp-luna-R-macosx-cocoa-x86_64.tar.gz)). - -##Apache Celix Bundle project -Now that Apache Celix and Eclipse is installed, we are ready to create a new Apache Celix Bundle project. In this project cmake will be create a singe hello world bundle with a deployment configuration for testing the bundle. - -To setup of the project, first create a new project dir to work in: - -```bash -#Create a new workspace to work in, e.g: -mkdir ${HOME}/workspace -export WS=${HOME}/workspace - -mkdir ${WS}/myproject -cd ${WS}/myproject -``` -Then create a CMakeLists.txt file - the makefile variant of CMake -in project root directory: - -```cmake -#${WS}/myproject/CMakeLists.txt - -#PART 1 -cmake_minimum_required(VERSION 3.2) -project(myproject C) - -#PART 2 -#Note. If celix is not installed in /usr/local dir, change the location accordingly. -set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/usr/local/share/celix/cmake/modules") -find_package(CELIX REQUIRED) -include_directories(${CELIX_INCLUDE_DIRS}) - -#PART 3 -add_subdirectory(bundles/hello_world) -``` - -This CMakeLists.txt file, sets up the following: - -* Part 1 - * The minimum cmake version required. - * The project name - * The type of source files to expect, in this case C. -* Part 2 - * The CMake module path to be used (e.g. where CMake find_package module can be found) - * That Celix package should be searched, configured and that the Celix package is required. - * That for all build targets in this CMakeLists.txt file or any sub directory CMakeLists.txt files the Apache Celix headers directory should be included. -* Part 3 - * The CMakelists.txt file in the subdirectory bundles/hello_world should also be processed. - - -It is a good pratice to create a seperate CMakeLists.txt file for every bundle you want to build. For the hello_world bundle a CMakeLists.txt file should be created in the bundles/hello_world sub directory. - -Create the sub directory: - -```CMake -#Create directory structure for the hello_world bundles -cd ${WS}/myproject -mkdir -p bundles/hello_world/private/src -``` - - -And add the following CMakeList.txt file: - -```CMake -#${WS}/myproject/bundles/hello_world/CMakeLists.txt - -add_bundle(hello_world - VERSION 1.0.0 - SOURCES - private/src/hello_world_activator -) -``` - -This CMakeLists.txt file declares that a bundle should be build based on the build result (shared library) of the declared sources (in this caese the private/src/hello_world_activator.c source). The add_bundle function is an Apache Celix specific CMake extension. - -What to create/destroy and how do when starting/stopping a bundle must programmed in the bundle activator. create and starting a bundle is seperated to make a clear seperation between the instantion/creation of a structure (e.g. object) and exposure of that instantation to other parts of the program. The same, but then reserve hold for seperating stopping and destroying a bundle. - -```C -//${WS}/myproject/bundles/hello_world/private/src/hello_world_activator.c -#include <stdlib.h> -#include <stdio.h> - -#include "bundle_activator.h" -#include "bundle_context.h" - - -struct userData { - char * word; -}; - -celix_status_t bundleActivator_create(bundle_context_pt context, void **userData) { - celix_status_t status = CELIX_SUCCESS; - *userData = malloc(sizeof(struct userData)); - if (userData != NULL) { - ((struct userData *)(*userData))->word = "World"; - } else { - status = CELIX_START_ERROR; - } - return CELIX_SUCCESS; -} - -celix_status_t bundleActivator_start(void * userData, bundle_context_pt context) { - struct userData * data = (struct userData *) userData; - printf("Hello %s\n", data->word); - return CELIX_SUCCESS; -} - -celix_status_t bundleActivator_stop(void * userData, bundle_context_pt context) { - struct userData * data = (struct userData *) userData; - printf("Goodbye %s\n", data->word); - return CELIX_SUCCESS; -} - -celix_status_t bundleActivator_destroy(void * userData, bundle_context_pt context) { - free(userData); - return CELIX_SUCCESS; -} -``` - -###Building -One of the highly recommended features of CMake is the ability to do out of source builds, the benefit is that all of the build results will go in a seperate directory without cluttering the (source) project. To create the build directory and build the project execute the following commands: - -```bash -cd ${WS} -mkdir myproject/build -cd myproject/build -cmake .. -make all -#Or -#cmake -G Ninja .. -#ninja -``` - -Hopefully you will some some build results scrolling over the screen and actual build results in the build directory. There should be a hello_world.zip in the bundles/hello_world directory, this the actual bundle. But a bundle on its own has no real value, so lets setup a deployment and run the Apache Celix framwork with this bundle. - - -###Running - -To create a deployment for the hello_world bundle two things are needed: - -1. Add a `add_deploy` statement in the `bundles/hello_world/CMakeLists.txt` file declaring what to deploy and under which name. - -```CMake -#${WS}/myproject/bundles/hello_world/CMakeLists.txt -add_deploy("myproject-deploy" BUNDLES - ${CELIX_BUNDLES_DIR}/shell.zip - ${CELIX_BUNDLES_DIR}/shell_tui.zip - hello_world -) -``` - -Rerun make again form the build project. the make files genereated by CMake will ensure cmake is runned again to update the actual make files. - -```bash -cd ${WS}/myproject-build -make -j -#or -#ninja -``` - -Now a deploy directory myproject should be availabe in the deploy directory. This directory contains - among other files - the run.sh script. This can be used to run the Apache Celix framework with the declared bundles from the deploy.cmake. - -```bash -cd ${WS}/myproject-build/deploy/myproject-deploy -. ./release.sh -celix -``` - -The hello_world bundle should be started with the famous "Hello World" text printed. The shell and shell_tui bundle are also deployed and these can be used to query and control the running framework. Below some commands are shown for querying the installed bundles, listing all known shell command, showing the help of a specific command and stopping a specific bundle (note that bundle 0 is the framework "bundle"): - -``` -lb -help -help inspect -stop 0 -``` - -##Apache Celix Bundle Project in Eclipse - -A nice feature of CMake is the ability to generate Eclipse project files, with this feature bundles can also be developed with use of Eclipse. This should help speed up the development process. -To get started change directory to the build directory and generate a eclipse project file. - - cd ${WS}/myproject-build - cmake -G "Eclipse CDT4 - Unix Makefiles" . - -Startup the Eclipse EDI and a chose the `${WS}` - - - -Import the project with existing project. - - - -To build the project, use Project->Build All. To run or debug from Eclipse navigate to the myproject deploy directory and right click on the 'myproject-deploy.launch' file. And select Run As or Debug As to run or debug the bundle. - - - - - - - - - - +##Guides +There are several guide to help you get started. The first guide is [Getting Started: Creating a simple bundle](creating_a_simple_bundle.md) and this should get you started for your first C or C++ bundle. +After that you can extend the example by providing and use services using the +guide [Getting Started: Using Services with C](using_services_for_c.md) or [Getting Started: Using Services with C++](using_services_with_cxx.md). http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/getting_started/using_services_with_c.md ---------------------------------------------------------------------- diff --git a/documents/getting_started/using_services_with_c.md b/documents/getting_started/using_services_with_c.md new file mode 100644 index 0000000..b098f48 --- /dev/null +++ b/documents/getting_started/using_services_with_c.md @@ -0,0 +1,585 @@ +#Apache Celix - Best Practices + +## Intro + +This example should give a best practice approach for providing and using service with Apache Celix. + +## Services + +To start-of, services in Celix are just a pointer to a memory location registered in the service registry using a name and an optional set of key/value pairs. + +By convention use the following service layout: + +```C +//example.h +#ifndef EXAMPLE_H_ +#define EXAMPLE_H_ + +#define EXAMPLE_NAME "org.example" +#define EXAMPLE_VERSION "1.0.0" +#define EXAMPLE_CONSUMER_RANGE "[1.0.0,2.0.0)" + + +struct example_struct { + void *handle; + int (*method)(void *handle, int arg1, double arg2, double *result); +} ; + +typedef struct example_struct example_t; + +#endif /* EXAMPLE_H_ */ + +``` + + +For a Celix service a service name, service version and service consumer range should be declared. +This is explicitly done with macros to prevent symbols so to that no linking dependencies are introduced. + +Then the actual struct for the service needs to be declared. +The first element of the service struct should be a handle which can be used to store the service context, as convention we keep this pointer a void pointer to explicitly make it opaque. +Note that also an opaque struct could be used (e.g a declared but not defined struct), but this can become problematic concerning components registering multiple services. +In that case explicit cast are needed to prevent warning and this can be confusing for the To prevent that issues void pointers are preferred. + +The rest of the element should be function pointers, which by convention should return an celix_status_t or int (which is technically the same). +The return value is used as a way of handling errors and is also needed to be able to make remote services (e.g. to be able to handle remote exceptions). + +The first argument of a service function should be the service handle and if there is a result the last argument should be a output parameter (either pre allocated (e.g. double *) or not (e.g. double **)). +It is also possible to create typedef of the pointer to the service struct (e.g. typedef struct example_service *example_service_pt), but this is not needed. +If you do not create typedefs with pointers it is easier to include service struct in an parent struct (without memory allocation) and also make it's possible to use the const on the struct instead of the pointer. + +### Semantic Versioning + +For versioning, semantic versioning should be used. + +A backward incompatible change should lead to a major version increase (e.g. 1.0.0 -> 2.0.0). +For a C Service change that are incompatible are: + +- Removing a function +- Adding a function to before any other function +- Moving a function to an other location in the service struct +- Changing the signature of a function +- Changing the semantics of a argument (e.g. changing range input from "range in kilometer" to "range in meters") + +A backwards compatible change which extend the functionality should lead to a minor version increase (e.g. 1.0.0 -> 1.1.0). +Changes considered backwards compatible which extend the functionality are: + +- Adding a function to the back of the service struct + +A backwards compatible change which does not extend the functionality should lead to a micro version increase (e.g. 1.0.0 -> 1.0.1). +Changes considered backwards compatible which does not extend the functionaility are: + +- Changes in the documentation +- Renaming of arguments + + +## Components + +Component should use the ADT principle (see [ADT in C](http://inst.eecs.berkeley.edu/~selfpace/studyguide/9C.sg/Output/ADTs.in.C.html)). + +Components should have a `<cmpName>_create` and `<cmpName>_destroy` function. +Components can have a `<cmpName>_start` and `<cmpName>_stop` function to start/stop threads or invoke functionality needed a fully created component. +The start function will only be called if all required service are available and the stop function will be called when some required are going or if the component needs to be stopped. + +Components can also have a `<cmpName>_init` and `<cmpName>_deinit` function which will be called before and after respectively the start and stop function. +The init function can be used to add additional (even required) service dependencies. +The use case for init/deinit component functions are exceptional. + + +## Code Examples + +The next code block contains some code examples of components to indicate how to handle service dependencies, how to specify providing services and how to cope with locking/synchronizing. +The complete example can be found [here](../../examples/best_practice_example). + +The error checking is very minimal in these example to keep the focus on how to interact with services and how to deal with errors in C / Celix. + + +### Bar example + +The bar example is a simple component providing the `example` service. + +```C +//bar.h +#ifndef BAR_H_ +#define BAR_H_ + +#include "example.h" + +typedef struct bar_struct bar_t; + +bar_t* bar_create(void); +void bar_destroy(bar_t *self); + +int bar_method(bar_t *self, int arg1, double arg2, double *out); + +#endif //BAR_H_ +``` + +```C +//bar.c +#define OK 0 +#define ERROR 1 + +struct bar_struct { + double prefValue; +}; + +bar_t* bar_create(void) { + bar_t *self = calloc(1, sizeof(*self)); + if (self != NULL) { + self->prefValue = 42; + } else { + //log error + } + return self; +}; + +void bar_destroy(bar_t *self) { + free(self); +} + +int bar_method(bar_t *self, int arg1, double arg2, double *out) { + double update = (self->prefValue + arg1) * arg2; + self->prefValue = update; + *out = update; + return OK; +} +``` + +```C +//bar_activator.c +#include "dm_activator.h" +#include "bar.h" + +#include <stdlib.h> + +struct activator { + bar_t *bar; + example_t exampleService; +}; + +celix_status_t dm_create(bundle_context_pt context, void **userData) { + celix_status_t status = CELIX_SUCCESS; + struct activator *act = calloc(1, sizeof(*act)); + if (act != NULL) { + + act->bar = bar_create(); + act->exampleService.handle = act->bar; + act->exampleService.method = (void*) bar_method; + + if (act->bar != NULL) { + *userData = act; + } else { + free(act); + } + } else { + status = CELIX_ENOMEM; + } + return status; +} + +celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + + dm_component_pt cmp = NULL; + component_create(context, "BAR", &cmp); + component_setImplementation(cmp, activator->bar); + component_addInterface(cmp, EXAMPLE_NAME, EXAMPLE_VERSION, &activator->exampleService, NULL); + + dependencyManager_add(manager, cmp); + return status; +} + +celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + bar_destroy(activator->bar); + free(activator); + return status; +}; +``` + +### Foo1 example + +The Foo1 example shows how add a service dependency, implement the callback, invoke a service and how to protect the usage of service with use of a mutex. + +```C +//foo1.h +#ifndef FOO1_H_ +#define FOO1_H_ + +#include "example.h" + +typedef struct foo1_struct foo1_t; + +foo1_t* foo1_create(void); +void foo1_destroy(foo1_t *self); + +int foo1_start(foo1_t *self); +int foo1_stop(foo1_t *self); + +int foo1_setExample(foo1_t *self, const example_t *example); + + +#endif //FOO1_H_ +``` + +```C +//foo1.c +#include "foo1.h" + +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <string.h> +#include <signal.h> +#include <stdbool.h> +#include <pthread.h> +#include <assert.h> + + +#define OK 0 +#define ERROR 1 + +static void* foo1_thread(void*); + +struct foo1_struct { + const example_t *example; + pthread_mutex_t mutex; //protecting example + pthread_t thread; + bool running; +}; + +foo1_t* foo1_create(void) { + foo1_t *self = calloc(1, sizeof(*self)); + if (self != NULL) { + pthread_mutex_init(&self->mutex, NULL); + self->running = false; + } else { + //log error + } + return self; +}; + +void foo1_destroy(foo1_t *self) { + assert(!self->running); + pthread_mutex_destroy(&self->mutex); + free(self); +} + +int foo1_start(foo1_t *self) { + self->running = true; + pthread_create(&self->thread, NULL, foo1_thread, self); + return OK; +} + +int foo1_stop(foo1_t *self) { + self->running = false; + pthread_kill(self->thread, SIGUSR1); + pthread_join(self->thread, NULL); + return OK; +} + +int foo1_setExample(foo1_t *self, const example_t *example) { + pthread_mutex_lock(&self->mutex); + self->example = example; //NOTE could be NULL if req is not mandatory + pthread_mutex_unlock(&self->mutex); + return OK; +} + +static void* foo1_thread(void *userdata) { + foo1_t *self = userdata; + double result; + int rc; + while (self->running) { + pthread_mutex_lock(&self->mutex); + if (self->example != NULL) { + rc = self->example->method(self->example->handle, 1, 2.0, &result); + if (rc == 0) { + printf("Result is %f\n", result); + } else { + printf("Error invoking method for example\n"); + } + } + pthread_mutex_unlock(&self->mutex); + usleep(10000000); + } + return NULL; +} +``` + +```C +//foo1_activator.c +#include "dm_activator.h" +#include "foo1.h" + +#include <stdlib.h> + +struct activator { + foo1_t *foo; +}; + +celix_status_t dm_create(bundle_context_pt context, void **userData) { + celix_status_t status = CELIX_SUCCESS; + struct activator *act = calloc(1, sizeof(*act)); + if (act != NULL) { + act->foo = foo1_create(); + if (act->foo != NULL) { + *userData = act; + } else { + free(act); + } + } else { + status = CELIX_ENOMEM; + } + return status; +} + +celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + + dm_component_pt cmp = NULL; + component_create(context, "FOO1", &cmp); + component_setImplementation(cmp, activator->foo); + + /* + With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component + with type foo1_t* + */ + component_setCallbacksSafe(cmp, foo1_t*, NULL, foo1_start, foo1_stop, NULL); + + dm_service_dependency_pt dep = NULL; + serviceDependency_create(&dep); + serviceDependency_setRequired(dep, true); + serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL); + serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING); + + /* + With the serviceDependency_setCallbacksSafe we register callbacks when a service + is added and about to be removed for the component type foo1_t* and service type example_t*. + + We should protect the usage of the + service because after removal of the service the memory location of that service + could be freed + */ + serviceDependency_setCallbacksSafe(dep, foo1_t*, const example_t*, foo1_setExample, NULL, NULL, NULL, NULL); + component_addServiceDependency(cmp, dep); + + dependencyManager_add(manager, cmp); + + return status; +} + +celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + foo1_destroy(activator->foo); + free(activator); + return status; +}; + +``` + +### Foo2 example + +The Foo2 example shows how to cope with multiple services and how to remove the need for locking by ensuring only access to the services and the services container by a single thread. + +```C +//foo2.h +#ifndef FOO2_H_ +#define FOO2_H_ + +#include "example.h" + +typedef struct foo2_struct foo2_t; + +foo2_t* foo2_create(void); +void foo2_destroy(foo2_t *self); + +int foo2_start(foo2_t *self); +int foo2_stop(foo2_t *self); + +int foo2_addExample(foo2_t *self, const example_t *example); +int foo2_removeExample(foo2_t *self, const example_t *example); + +#endif //FOO2_H_ +``` + +```C +//foo2.c +#include "foo2.h" + +#include "array_list.h" + +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <string.h> +#include <signal.h> +#include <stdbool.h> +#include <pthread.h> +#include <assert.h> + + +#define OK 0 +#define ERROR 1 + +static void* foo2_thread(void*); + +struct foo2_struct { + array_list_pt examples; + pthread_t thread; + bool running; +}; + +foo2_t* foo2_create(void) { + foo2_t *self = calloc(1, sizeof(*self)); + if (self != NULL) { + self->examples = NULL; + arrayList_create(&self->examples); + self->running = false; + } else { + //log error + } + return self; +}; + +void foo2_destroy(foo2_t *self) { + assert(!self->running); + arrayList_destroy(self->examples); + free(self); +} + +int foo2_start(foo2_t *self) { + self->running = true; + pthread_create(&self->thread, NULL, foo2_thread, self); + return OK; +} + +int foo2_stop(foo2_t *self) { + self->running = false; + pthread_kill(self->thread, SIGUSR1); + pthread_join(self->thread, NULL); + return OK; +} + +int foo2_addExample(foo2_t *self, const example_t *example) { + //NOTE foo2 is suspended -> thread is not running -> safe to update + int status = OK; + status = arrayList_add(self->examples, (void *)example); + return status; +} + +int foo2_removeExample(foo2_t *self, const example_t *example) { + //NOTE foo2 is suspended -> thread is not running -> safe to update + int status = OK; + status = arrayList_removeElement(self->examples, (void*)example); + return status; +} + +static void* foo2_thread(void *userdata) { + foo2_t *self = userdata; + double result; + int rc; + while (self->running) { + unsigned int size = arrayList_size(self->examples); + int i; + for (i = 0; i < size; i += 1) { + const example_t* example = arrayList_get(self->examples, i); + rc = example->method(example->handle, 1, 2.0, &result); + if (rc == 0) { + printf("Result is %f\n", result); + } else { + printf("Error invoking method for example\n"); + } + } + usleep(10000000); + } + return NULL; + +``` + +```C +//foo2_activator.c +#include "dm_activator.h" +#include "foo2.h" + +#include <stdlib.h> + +struct activator { + foo2_t *foo; +}; + +celix_status_t dm_create(bundle_context_pt context, void **userData) { + celix_status_t status = CELIX_SUCCESS; + struct activator *act = calloc(1, sizeof(*act)); + if (act != NULL) { + act->foo = foo2_create(); + if (act->foo != NULL) { + *userData = act; + } else { + free(act); + } + } else { + status = CELIX_ENOMEM; + } + return status; +} + +celix_status_t dm_init(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + + dm_component_pt cmp = NULL; + component_create(context, "FOO2", &cmp); + component_setImplementation(cmp, activator->foo); + + /* + With the component_setCallbacksSafe we register callbacks when a component is started / stopped using a component + with type foo1_t* + */ + component_setCallbacksSafe(cmp, foo2_t*, NULL, foo2_start, foo2_stop, NULL); + + dm_service_dependency_pt dep = NULL; + serviceDependency_create(&dep); + serviceDependency_setRequired(dep, false); + serviceDependency_setService(dep, EXAMPLE_NAME, EXAMPLE_CONSUMER_RANGE, NULL); + serviceDependency_setStrategy(dep, DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND); + + /* + With the serviceDependency_setCallbacksSafe we register callbacks when a service + is added and about to be removed for the component type foo1_t* and service type example_t*. + + We should protect the usage of the + service because after removal of the service the memory location of that service + could be freed + */ + serviceDependency_setCallbacksSafe(dep, foo2_t*, const example_t*, NULL, foo2_addExample, foo2_removeExample, NULL, NULL); + component_addServiceDependency(cmp, dep); + + dependencyManager_add(manager, cmp); + + return status; +} + +celix_status_t dm_destroy(void *userData, bundle_context_pt context, dm_dependency_manager_pt manager) { + celix_status_t status = CELIX_SUCCESS; + struct activator *activator = userData; + foo2_destroy(activator->foo); + free(activator); + return status; +}; +``` + +## Locking and Suspending + +As you may notice, the Foo1 example uses locks. +In principle, locking is necessary in order to ensure coherence in case service dependencies are removed/added/changed; on the other hands, locking increases latency and, when misused, can lead to poor performance. +For this reason, the serviceDependecy interface gives the possibility to choose between a locking and suspend (a non-locking) strategy through the serviceDependency_setStrategy function, as is used in the Foo2 example. + +The locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING` notifies the component in case the dependencies' set changes (e.g. a dependency is added/removed): the component is responsible for protecting via locks the dependencies' list and check (always under lock) if the service he's depending on is still available. +The suspend or non-locking strategy `DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND` (default when no strategy is explicitly set) reliefs the programmer from dealing with service dependencies' consistency issues: in case this strategy is adopted, the component is stopped and restarted (i.e. temporarily suspended) upon service dependencies' changes. + +The suspend strategy has the advantage of reducing locks' usage: of course, suspending the component has its own overhead (e.g. stopping and restarting threads), but this overhead is "paid" only in case of changes in service dependencies, while the locking overhead is always paid. + http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/documents/intro/readme.md ---------------------------------------------------------------------- diff --git a/documents/intro/readme.md b/documents/intro/readme.md index 4d2ea99..7557e5a 100644 --- a/documents/intro/readme.md +++ b/documents/intro/readme.md @@ -133,5 +133,4 @@ For more information see: * [Apache Celix - Building and Installing] (../building/readme.md) * [Apache Celix - Getting Started Guide](../getting_started/readme.md) -* [Apache Celix - Best Practices](../best_practices/readme.md) * [Apache Celix - CMake Commands](../cmake_commands/readme.md) http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase1/include/Phase1Activator.h ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase1/include/Phase1Activator.h b/examples/dm_example_cxx/phase1/include/Phase1Activator.h index f1157f6..6029cec 100644 --- a/examples/dm_example_cxx/phase1/include/Phase1Activator.h +++ b/examples/dm_example_cxx/phase1/include/Phase1Activator.h @@ -29,8 +29,8 @@ class Phase1Activator : public DmActivator { command_service_t cmd {}; public: Phase1Activator(DependencyManager& mng) : DmActivator(mng) {} - virtual void init(DependencyManager& manager); - virtual void deinit(DependencyManager& manager); + virtual void init(); + virtual void deinit(); }; #endif //CELIX_PHASE1ACTIVATOR_H http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase1/src/Phase1Activator.cc ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase1/src/Phase1Activator.cc b/examples/dm_example_cxx/phase1/src/Phase1Activator.cc index f322195..2f84d8e 100644 --- a/examples/dm_example_cxx/phase1/src/Phase1Activator.cc +++ b/examples/dm_example_cxx/phase1/src/Phase1Activator.cc @@ -31,7 +31,7 @@ DmActivator* DmActivator::create(DependencyManager& mng) { return new Phase1Activator(mng); } -void Phase1Activator::init(DependencyManager& manager) { +void Phase1Activator::init() { std::shared_ptr<Phase1Cmp> cmp {new Phase1Cmp()}; Properties cmdProps; @@ -52,6 +52,6 @@ void Phase1Activator::init(DependencyManager& manager) { .setCallbacks(&Phase1Cmp::init, &Phase1Cmp::start, &Phase1Cmp::stop, &Phase1Cmp::deinit); } -void Phase1Activator::deinit(DependencyManager& manager) { +void Phase1Activator::deinit() { //nothing to do } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase2/include/Phase2Activator.h ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase2/include/Phase2Activator.h b/examples/dm_example_cxx/phase2/include/Phase2Activator.h index 9e89f0b..069b2ae 100644 --- a/examples/dm_example_cxx/phase2/include/Phase2Activator.h +++ b/examples/dm_example_cxx/phase2/include/Phase2Activator.h @@ -27,8 +27,8 @@ using namespace celix::dm; class Phase2Activator : public DmActivator { public: Phase2Activator(DependencyManager& mng) : DmActivator(mng) {} - virtual void init(DependencyManager& manager); - virtual void deinit(DependencyManager& manager); + virtual void init(); + virtual void deinit(); }; #endif //CELIX_PHASE2AACTIVATOR_H http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase2a/src/Phase2aActivator.cc ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase2a/src/Phase2aActivator.cc b/examples/dm_example_cxx/phase2a/src/Phase2aActivator.cc index c8b4659..8a640ec 100644 --- a/examples/dm_example_cxx/phase2a/src/Phase2aActivator.cc +++ b/examples/dm_example_cxx/phase2a/src/Phase2aActivator.cc @@ -29,7 +29,7 @@ DmActivator* DmActivator::create(DependencyManager& mng) { } -void Phase2Activator::init(DependencyManager& manager) { +void Phase2Activator::init() { Properties props {}; props["name"] = "phase2a"; @@ -48,6 +48,6 @@ void Phase2Activator::init(DependencyManager& manager) { .setCallbacks(&Phase2Cmp::setLogService); } -void Phase2Activator::deinit(DependencyManager& manager) { +void Phase2Activator::deinit() { } http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase2b/src/Phase2bActivator.cc ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase2b/src/Phase2bActivator.cc b/examples/dm_example_cxx/phase2b/src/Phase2bActivator.cc index f972d9d..101e813 100644 --- a/examples/dm_example_cxx/phase2b/src/Phase2bActivator.cc +++ b/examples/dm_example_cxx/phase2b/src/Phase2bActivator.cc @@ -28,7 +28,7 @@ DmActivator* DmActivator::create(DependencyManager& mng) { return new Phase2Activator(mng); } -void Phase2Activator::init(DependencyManager& manager) { +void Phase2Activator::init() { Properties props {}; props["name"] = "phase2b"; @@ -46,6 +46,6 @@ void Phase2Activator::init(DependencyManager& manager) { .setCallbacks(&Phase2Cmp::setLogService); } -void Phase2Activator::deinit(DependencyManager& manager) { +void Phase2Activator::deinit() { } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase3/include/Phase3Activator.h ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase3/include/Phase3Activator.h b/examples/dm_example_cxx/phase3/include/Phase3Activator.h index f058d46..fc66c28 100644 --- a/examples/dm_example_cxx/phase3/include/Phase3Activator.h +++ b/examples/dm_example_cxx/phase3/include/Phase3Activator.h @@ -27,7 +27,7 @@ using namespace celix::dm; class Phase3Activator : public DmActivator { public: Phase3Activator(DependencyManager& mng) : DmActivator(mng) {} - virtual void init(DependencyManager& manager); + virtual void init(); }; #endif //CELIX_PHASE2AACTIVATOR_H http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase3/src/Phase3Activator.cc ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase3/src/Phase3Activator.cc b/examples/dm_example_cxx/phase3/src/Phase3Activator.cc index 4688fb0..ef8cb86 100644 --- a/examples/dm_example_cxx/phase3/src/Phase3Activator.cc +++ b/examples/dm_example_cxx/phase3/src/Phase3Activator.cc @@ -28,7 +28,7 @@ DmActivator* DmActivator::create(DependencyManager& mng) { return new Phase3Activator(mng); } -void Phase3Activator::init(DependencyManager& manager) { +void Phase3Activator::init() { Component<Phase3Cmp>& cmp = createComponent<Phase3Cmp>() //NOTE no setInstance -> lazy initialization using the default constructor .setCallbacks(nullptr, &Phase3Cmp::start, &Phase3Cmp::stop, nullptr); http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase3_locking/include/Phase3LockingActivator.h ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase3_locking/include/Phase3LockingActivator.h b/examples/dm_example_cxx/phase3_locking/include/Phase3LockingActivator.h index 9a84dc9..78d1748 100644 --- a/examples/dm_example_cxx/phase3_locking/include/Phase3LockingActivator.h +++ b/examples/dm_example_cxx/phase3_locking/include/Phase3LockingActivator.h @@ -27,7 +27,7 @@ using namespace celix::dm; class Phase3LockingActivator : public DmActivator { public: Phase3LockingActivator(DependencyManager& mng) : DmActivator(mng) {} - virtual void init(DependencyManager& manager); + virtual void init(); }; #endif //CELIX_PHASE3LOCKINGAACTIVATOR_H http://git-wip-us.apache.org/repos/asf/celix/blob/3c0bcf36/examples/dm_example_cxx/phase3_locking/src/Phase3LockingActivator.cc ---------------------------------------------------------------------- diff --git a/examples/dm_example_cxx/phase3_locking/src/Phase3LockingActivator.cc b/examples/dm_example_cxx/phase3_locking/src/Phase3LockingActivator.cc index 9819824..c682371 100644 --- a/examples/dm_example_cxx/phase3_locking/src/Phase3LockingActivator.cc +++ b/examples/dm_example_cxx/phase3_locking/src/Phase3LockingActivator.cc @@ -28,7 +28,7 @@ DmActivator* DmActivator::create(DependencyManager& mng) { return new Phase3LockingActivator(mng); } -void Phase3LockingActivator::init(DependencyManager& manager) { +void Phase3LockingActivator::init() { Component<Phase3LockingCmp>& cmp = createComponent<Phase3LockingCmp>() //NOTE no setInstance -> lazy initialization using the default constructor .setCallbacks(nullptr, &Phase3LockingCmp::start, &Phase3LockingCmp::stop, nullptr);
