celix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pnol...@apache.org
Subject [1/2] celix git commit: CELIX-368: Adds best practices documentation and best practice example
Date Thu, 21 Jul 2016 12:29:43 GMT
Repository: celix
Updated Branches:
  refs/heads/develop 0757a7a62 -> 8160dec5d


CELIX-368: Adds best practices documentation and best practice example


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

Branch: refs/heads/develop
Commit: e175c8008cb0e60effbb264514cef7e0b47d8f10
Parents: 0757a7a
Author: Pepijn Noltes <pepijnnoltes@gmail.com>
Authored: Thu Jul 21 14:18:41 2016 +0200
Committer: Pepijn Noltes <pepijnnoltes@gmail.com>
Committed: Thu Jul 21 14:18:41 2016 +0200

----------------------------------------------------------------------
 .../public/include/dm_service_dependency.h      |  12 +-
 documents/best_practices/README.md              | 584 +++++++++++++++++++
 examples/CMakeLists.txt                         |   2 +
 examples/best_practice_example/CMakeLists.txt   |  42 ++
 examples/best_practice_example/README.md        |   3 +
 examples/best_practice_example/api/example.h    |  34 ++
 .../best_practice_example/bar/CMakeLists.txt    |  39 ++
 .../bar/private/include/bar.h                   |  32 +
 .../best_practice_example/bar/private/src/bar.c |  58 ++
 .../bar/private/src/bar_activator.c             |  70 +++
 .../best_practice_example/foo1/CMakeLists.txt   |  39 ++
 .../foo1/private/include/foo1.h                 |  36 ++
 .../foo1/private/src/foo1.c                     |  99 ++++
 .../foo1/private/src/foo1_activator.c           |  88 +++
 .../best_practice_example/foo2/CMakeLists.txt   |  39 ++
 .../foo2/private/include/foo2.h                 |  36 ++
 .../foo2/private/src/foo2.c                     | 109 ++++
 .../foo2/private/src/foo2_activator.c           |  88 +++
 examples/dm_example/CMakeLists.txt              |   6 +-
 19 files changed, 1407 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/dependency_manager/public/include/dm_service_dependency.h
----------------------------------------------------------------------
diff --git a/dependency_manager/public/include/dm_service_dependency.h b/dependency_manager/public/include/dm_service_dependency.h
index bed9379..3a9dc73 100644
--- a/dependency_manager/public/include/dm_service_dependency.h
+++ b/dependency_manager/public/include/dm_service_dependency.h
@@ -75,13 +75,13 @@ celix_status_t serviceDependency_setRequired(dm_service_dependency_pt dependency
 /**
  * Specify if the service dependency update strategy.
  *
- * For DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING the component is expected to use locking mechanismes when updating
- * and invoking services.
+ * The DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING strategy 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.
  *
- * For DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND the component is stopped/started
- * when services are set,added, modified or removed.
- * It is the responsibility of the component to ensure that no
- * service invocation is possible or happening when the component stop callback is finished.
+ * The 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.
  *
  * Default strategy is DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND
  */

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/documents/best_practices/README.md
----------------------------------------------------------------------
diff --git a/documents/best_practices/README.md b/documents/best_practices/README.md
new file mode 100644
index 0000000..63a61c9
--- /dev/null
+++ b/documents/best_practices/README.md
@@ -0,0 +1,584 @@
+# Best Practice Example
+
+## 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 [http://lmgtfy.com/?q=ADT+in+C](http://lmgtfy.com/?q=ADT+in+C)).
+
+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/e175c800/examples/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 7de04ca..04f2bd4 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -19,6 +19,8 @@ if (EXAMPLES)
     add_subdirectory(hello_world)
     add_subdirectory(hello_world_test)
 
+    add_subdirectory(best_practice_example)
+
     if (NOT ANDROID)
     	add_subdirectory(mongoose)
     endif()

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/CMakeLists.txt b/examples/best_practice_example/CMakeLists.txt
new file mode 100644
index 0000000..1b94159
--- /dev/null
+++ b/examples/best_practice_example/CMakeLists.txt
@@ -0,0 +1,42 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+if (BUILD_DEPENDENCY_MANAGER)
+
+    include_directories(
+            ${PROJECT_SOURCE_DIR}/dependency_manager/public/include
+            ${PROJECT_SOURCE_DIR}/utils/public/include
+            api
+    )
+
+    add_subdirectory(foo1)
+    add_subdirectory(foo2)
+    add_subdirectory(bar)
+
+    add_deploy(best-practice-example
+        COPY
+        BUNDLES
+            shell
+            shell_tui
+            dm_shell
+            bar
+            foo1
+            foo2
+        PROPERTIES
+            example=value
+    )
+
+endif ()

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/README.md
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/README.md b/examples/best_practice_example/README.md
new file mode 100644
index 0000000..3f678b6
--- /dev/null
+++ b/examples/best_practice_example/README.md
@@ -0,0 +1,3 @@
+# Best Practice Example
+
+For more information about this example see [Best Practices](../../documents/best_practices/README.md)
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/api/example.h
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/api/example.h b/examples/best_practice_example/api/example.h
new file mode 100644
index 0000000..b0e0166
--- /dev/null
+++ b/examples/best_practice_example/api/example.h
@@ -0,0 +1,34 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+#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_ */

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/bar/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/bar/CMakeLists.txt b/examples/best_practice_example/bar/CMakeLists.txt
new file mode 100644
index 0000000..7ebb45c
--- /dev/null
+++ b/examples/best_practice_example/bar/CMakeLists.txt
@@ -0,0 +1,39 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+include_directories(
+        private/include
+)
+
+add_bundle(bar
+    SYMBOLIC_NAME bar
+    VERSION 1.0.0
+    SOURCES
+        private/src/bar_activator
+        private/src/bar.c
+)
+
+IF(APPLE)
+    target_link_libraries(bar celix_framework -Wl,-all_load dependency_manager_static)
+else()
+    if(ENABLE_ADDRESS_SANITIZER)
+        #With asan there can be undefined symbols
+        target_link_libraries(bar -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    else()
+        target_link_libraries(bar -Wl,--no-undefined -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    endif()
+endif()

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/bar/private/include/bar.h
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/bar/private/include/bar.h b/examples/best_practice_example/bar/private/include/bar.h
new file mode 100644
index 0000000..5e1da8b
--- /dev/null
+++ b/examples/best_practice_example/bar/private/include/bar.h
@@ -0,0 +1,32 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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_

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/bar/private/src/bar.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/bar/private/src/bar.c b/examples/best_practice_example/bar/private/src/bar.c
new file mode 100644
index 0000000..5099201
--- /dev/null
+++ b/examples/best_practice_example/bar/private/src/bar.c
@@ -0,0 +1,58 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#include "bar.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
+
+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;
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/bar/private/src/bar_activator.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/bar/private/src/bar_activator.c b/examples/best_practice_example/bar/private/src/bar_activator.c
new file mode 100644
index 0000000..0fa7889
--- /dev/null
+++ b/examples/best_practice_example/bar/private/src/bar_activator.c
@@ -0,0 +1,70 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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;
+};
+

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo1/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo1/CMakeLists.txt b/examples/best_practice_example/foo1/CMakeLists.txt
new file mode 100644
index 0000000..0d1b93c
--- /dev/null
+++ b/examples/best_practice_example/foo1/CMakeLists.txt
@@ -0,0 +1,39 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+include_directories(
+        private/include
+)
+
+add_bundle(foo1
+    SYMBOLIC_NAME foo1
+    VERSION 1.0.0
+    SOURCES
+        private/src/foo1_activator
+        private/src/foo1.c
+)
+
+IF(APPLE)
+    target_link_libraries(foo1 celix_framework -Wl,-all_load dependency_manager_static)
+else()
+    if(ENABLE_ADDRESS_SANITIZER)
+        #With asan there can be undefined symbols
+        target_link_libraries(foo1 -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    else()
+        target_link_libraries(foo1 -Wl,--no-undefined -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    endif()
+endif()

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo1/private/include/foo1.h
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo1/private/include/foo1.h b/examples/best_practice_example/foo1/private/include/foo1.h
new file mode 100644
index 0000000..f556b44
--- /dev/null
+++ b/examples/best_practice_example/foo1/private/include/foo1.h
@@ -0,0 +1,36 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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_

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo1/private/src/foo1.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo1/private/src/foo1.c b/examples/best_practice_example/foo1/private/src/foo1.c
new file mode 100644
index 0000000..ba8ce19
--- /dev/null
+++ b/examples/best_practice_example/foo1/private/src/foo1.c
@@ -0,0 +1,99 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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;
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo1/private/src/foo1_activator.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo1/private/src/foo1_activator.c b/examples/best_practice_example/foo1/private/src/foo1_activator.c
new file mode 100644
index 0000000..f94888b
--- /dev/null
+++ b/examples/best_practice_example/foo1/private/src/foo1_activator.c
@@ -0,0 +1,88 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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;
+};
+

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo2/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo2/CMakeLists.txt b/examples/best_practice_example/foo2/CMakeLists.txt
new file mode 100644
index 0000000..1096c6c
--- /dev/null
+++ b/examples/best_practice_example/foo2/CMakeLists.txt
@@ -0,0 +1,39 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+# 
+#   http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+include_directories(
+        private/include
+)
+
+add_bundle(foo2
+    SYMBOLIC_NAME foo2
+    VERSION 1.0.0
+    SOURCES
+        private/src/foo2_activator
+        private/src/foo2.c
+)
+
+IF(APPLE)
+    target_link_libraries(foo2 celix_framework -Wl,-all_load dependency_manager_static)
+else()
+    if(ENABLE_ADDRESS_SANITIZER)
+        #With asan there can be undefined symbols
+        target_link_libraries(foo2 -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    else()
+        target_link_libraries(foo2 -Wl,--no-undefined -Wl,--whole-archive dependency_manager_static -Wl,--no-whole-archive celix_framework)
+    endif()
+endif()

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo2/private/include/foo2.h
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo2/private/include/foo2.h b/examples/best_practice_example/foo2/private/include/foo2.h
new file mode 100644
index 0000000..9f09276
--- /dev/null
+++ b/examples/best_practice_example/foo2/private/include/foo2.h
@@ -0,0 +1,36 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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_
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo2/private/src/foo2.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo2/private/src/foo2.c b/examples/best_practice_example/foo2/private/src/foo2.c
new file mode 100644
index 0000000..932d42d
--- /dev/null
+++ b/examples/best_practice_example/foo2/private/src/foo2.c
@@ -0,0 +1,109 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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;
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/best_practice_example/foo2/private/src/foo2_activator.c
----------------------------------------------------------------------
diff --git a/examples/best_practice_example/foo2/private/src/foo2_activator.c b/examples/best_practice_example/foo2/private/src/foo2_activator.c
new file mode 100644
index 0000000..0f61e9a
--- /dev/null
+++ b/examples/best_practice_example/foo2/private/src/foo2_activator.c
@@ -0,0 +1,88 @@
+/**
+ *Licensed to the Apache Software Foundation (ASF) under one
+ *or more contributor license agreements.  See the NOTICE file
+ *distributed with this work for additional information
+ *regarding copyright ownership.  The ASF licenses this file
+ *to you under the Apache License, Version 2.0 (the
+ *"License"); you may not use this file except in compliance
+ *with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *Unless required by applicable law or agreed to in writing,
+ *software distributed under the License is distributed on an
+ *"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ *specific language governing permissions and limitations
+ *under the License.
+ */
+
+#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;
+};
+

http://git-wip-us.apache.org/repos/asf/celix/blob/e175c800/examples/dm_example/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/examples/dm_example/CMakeLists.txt b/examples/dm_example/CMakeLists.txt
index 18738ef..816d738 100644
--- a/examples/dm_example/CMakeLists.txt
+++ b/examples/dm_example/CMakeLists.txt
@@ -30,13 +30,13 @@ if (BUILD_DEPENDENCY_MANAGER)
     add_deploy("dm_example"
         COPY 
         BUNDLES
+            shell
+            shell_tui
+            dm_shell
             phase1
             phase2a
             phase2b
             phase3
-            shell
-            shell_tui
-            dm_shell
         PROPERTIES
             LOGHELPER_ENABLE_STDOUT_FALLBACK=true
     )


Mime
View raw message