Author: buildbot
Date: Mon Mar 9 20:11:15 2015
New Revision: 943058
Log:
Staging update by buildbot for felix
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/thread-model.html
Modified:
websites/staging/felix/trunk/content/ (props changed)
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Mar 9 20:11:15 2015
@@ -1 +1 @@
-1665335
+1665336
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/thread-model.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/thread-model.html
(added)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/thread-model.html
Mon Mar 9 20:11:15 2015
@@ -0,0 +1,165 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Felix - Apache Felix Dependency Manager - Thread
Model</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.css" type="text/css"
media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+ </head>
+ <body>
+ <div class="title">
+ <div class="logo">
+ <a href="http://felix.apache.org/";>
+ <img border="0" alt="Apache Felix" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><a href="/news.html">news</a> <br />
+<a href="/license.html">license</a> <br />
+<a href="/downloads.cgi">downloads</a> <br />
+<a href="/documentation.html">documentation</a> <br />
+<a href="/mailinglists.html">mailing lists</a> <br />
+<a href="/documentation/community/contributing.html">contributing</a> <br />
+<a href="/sitemap.html">site map</a> <br />
+<a href="http://www.apache.org/";>asf</a> <br />
+<a href="http://www.apache.org/security/";>security</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>sponsorship</a>
<br />
+<a href="http://www.apache.org/foundation/thanks.html";>sponsors</a> </p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left"
+ frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/subprojects.html">Apache Felix Subproject
Documentation</a> » <a
href="/documentation/subprojects/apache-felix-dependency-manager-4.html">Apache
Felix Dependency Manager 4</a>
+ </div>
+
+
+
+ <h1>Apache Felix Dependency Manager - Thread Model</h1>
+ <p>This section gives a brief overview of the default thread model used
by Dependency Manager, and also explains how to start and handle components
concurrently.</p>
+<h1 id="default-thread-model">Default Thread Model</h1>
+<p>By default, Dependency Manager uses a lock-free/single thread model:</p>
+<ul>
+<li>When an external event that influence the state of a Component is taking
place (for example, when a service dependency on which the Component is
depending on is registered in the
+registry by a given thread), then DependencyManager does not perform any
locking for the handling of the event. Instead of that, a job that will handle
the event is inserted in an internal
+lock-free Serial Queue which is internally maintained in each Component.</li>
+<li>All jobs scheduled in the Serial Queue are then executed in FIFO order, by
the first thread which has triggered the first event. This avoid to use some
blocking locks in DM internals, and
+also it simplifies the development of DM components, because all lifecycle
callbacks (init/start/stop/destroy) and dependency injections are scheduled
through the Serial Queue: This means
+that your component is not concurrently called in lifecycle callbacks and in
dependency injection methods.</li>
+<li>Now let's describe which thread is executing the jobs scheduled in a
Component Serial Queue: When a job (J1) is scheduled in the queue while it is
empty, then the current thread becomes
+the "master" and will immediately execute the Serial Queue tasks
(synchronously). And if another thread triggers another event concurrently
while the "master" thread is executing the job J1,
+then a job (J2) for this new event is just enqueued in the Serial Queue, but
the other thread returns immediately to the caller, and the job J2 will then be
executed by the "master" thread
+(after J1). </li>
+</ul>
+<p>This mechanism allows to serially handle all Component events (service
dependencies) in FIFO order without maintaining any locks. </p>
+<h1 id="enabling-parallelism-with-a-componentexecutorfactory">Enabling
parallelism with a ComponentExecutorFactory</h1>
+<p>As described above, all the external events that influence the state of a
given component are handed by jobs scheduled in the Serial Queue of the
Component, and the jobs are getting
+executed serially by a single "master" thread. So usually, bundles are started
from a single thread, meaning that all Components are then activated
synchronously.</p>
+<p>But when you register in the OSGi service registry a
ComponentExecutorFactory, that factory will be used by DependencyManager to
create an Executor of your choice for each Component,
+typically a shared threadpool configured by yourself. And all the Component
Serial Queues will be executed using the Executor returned by the
getExecutorFor(Component) method. However,
+jobs scheduled in the Serial Queue of a given Component are still executed one
at a time, in FIFO order and the Component remains single threaded, and
independent Components may then each
+be managed and activated concurrently with respect to each other.</p>
+<p>If you want to ensure that all Components are initialized after the
ComponentExecutorFactory is registered in the OSGI registry, you can use the
"org.apache.felix.dependencymanager.parallel"
+OSGi system property which specifies the list of components which must wait
for the ComponentExecutorFactory service. This property value can be set to a
wildcard ("*"), or a list of
+components implementation class prefixes (comma separated). So, all components
whose class name starts with the specified prefixes will be cached until the
ComponentExecutorFactory service
+is registered (In this way, it is not necessary to use the StartLevel service
if you want to ensure that all components are started concurrently).</p>
+<p>Some class name prefixes can also be negated (using "!"), in order to
exclude some components from the list of components using the
ComponentExecutorFactory service.</p>
+<p>Notice that if the ComponentExecutorFactory itself and all its dependent
services are defined using the Dependency Manager API, then you have to list
the package of such components with a
+"!" prefix, in order to indicate that those components must not wait for a
ComponentExecutorFactory service (since they are part of the
ComponentExecutorFactory implementation !). </p>
+<h1
id="examples-for-the-usage-of-the-orgapachefelixdependencymanagerparallel-property">Examples
for the usage of the "org.apache.felix.dependencymanager.parallel"
property:</h1>
+<div class="codehilite"><pre><span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span
class="n">dependencymanager</span><span class="p">.</span><span
class="n">parallel</span><span class="p">=</span><span class="o">*</span>
+ <span class="o">-></span> <span class="n">means</span> <span
class="n">all</span> <span class="n">components</span> <span
class="n">must</span> <span class="n">be</span> <span class="n">cached</span>
<span class="n">until</span> <span class="n">a</span> <span
class="n">ComponentExecutorFactory</span> <span class="n">comes</span> <span
class="n">up</span><span class="p">.</span>
+
+<span class="n">org</span><span class="p">.</span><span
class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span
class="n">dependencymanager</span><span class="p">.</span><span
class="n">parallel</span><span class="p">=</span><span
class="n">foo</span><span class="p">.</span><span class="n">bar</span><span
class="p">,</span> <span class="n">foo</span><span class="p">.</span><span
class="n">zoo</span>
+ <span class="o">-></span> <span class="n">means</span> <span
class="n">only</span> <span class="n">components</span> <span
class="n">whose</span> <span class="n">implementation</span> <span
class="n">class</span> <span class="n">names</span> <span class="n">are</span>
<span class="n">starting</span> <span class="n">with</span> "<span
class="n">foo</span><span class="p">.</span><span class="n">bar</span>"
<span class="n">or</span> "<span class="n">foo</span><span
class="p">.</span><span class="n">zoo</span>"
+ <span class="n">must</span> <span class="n">be</span> <span
class="n">handled</span> <span class="n">using</span> <span class="n">an</span>
<span class="n">Executor</span> <span class="n">returned</span> <span
class="n">by</span> <span class="n">the</span> <span
class="n">ComponentExecutorFactory</span> <span class="n">service</span><span
class="p">.</span> <span class="n">Other</span> <span
class="n">Components</span>
+ <span class="n">will</span> <span class="n">be</span> <span
class="n">handled</span> <span class="n">normally</span><span
class="p">,</span> <span class="n">as</span> <span class="n">when</span> <span
class="n">there</span> <span class="n">is</span> <span class="n">no</span>
<span class="n">ComponentExecutorFactory</span> <span
class="n">available</span><span class="p">.</span>
+
+<span class="n">org</span><span class="p">.</span><span
class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span
class="n">dependencymanager</span><span class="p">.</span><span
class="n">parallel</span><span class="p">=</span>!<span
class="n">foo</span><span class="p">.</span><span
class="n">threadpool</span><span class="p">,</span> <span class="o">*</span>
+ <span class="o">-></span> <span class="n">means</span> <span
class="n">all</span> <span class="n">components</span> <span
class="n">must</span> <span class="n">be</span> <span class="n">delayed</span>
<span class="n">until</span> <span class="n">the</span> <span
class="n">ComponentExecutorFactory</span> <span class="n">comes</span> <span
class="n">up</span><span class="p">,</span> <span class="n">except</span> <span
class="n">the</span>
+ <span class="n">components</span> <span class="n">whose</span> <span
class="n">implementations</span> <span class="n">class</span> <span
class="n">names</span> <span class="n">are</span> <span
class="n">starting</span> <span class="n">with</span> "<span
class="n">foo</span><span class="p">.</span><span
class="n">threadpool</span>" <span class="n">prefix</span><span
class="p">).</span>
+</pre></div>
+
+
+<h1
id="examples-of-a-componentexecutorfactory-that-provides-a-shared-threadpool">Examples
of a ComponentExecutorFactory that provides a shared threadpool:</h1>
+<p>First, we define the OSGi bundle context system property to enable
parallelism for all DM Components excepts the one which declares the
ComponentExecutorFactory:</p>
+<div class="codehilite"><pre><span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span
class="n">dependencymanager</span><span class="p">.</span><span
class="n">parallel</span><span class="p">=</span>!<span
class="n">com</span><span class="p">.</span><span class="n">acme</span><span
class="p">.</span><span class="n">management</span><span
class="p">.</span><span class="n">threadpool</span><span class="p">,</span>
<span class="o">*</span>
+</pre></div>
+
+
+<p>Next, here is the Activator which declares the ComponentExecutorFactory:</p>
+<div class="codehilite"><pre><span class="kn">package</span> <span
class="n">com</span><span class="o">.</span><span class="na">acme</span><span
class="o">.</span><span class="na">management</span><span
class="o">.</span><span class="na">threadpool</span><span class="o">;</span>
+<span class="kn">import</span> <span
class="nn">org.apache.felix.dm.*</span><span class="o">;</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">Activator</span> <span class="kd">extends</span> <span
class="n">DependencyActivatorBase</span> <span class="o">{</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">init</span><span class="o">(</span><span
class="n">BundleContext</span> <span class="n">context</span><span
class="o">,</span> <span class="n">DependencyManager</span> <span
class="n">mgr</span><span class="o">)</span> <span class="kd">throws</span>
<span class="n">Exception</span> <span class="o">{</span>
+ <span class="n">mgr</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span
class="n">createComponent</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">setInterface</span><span
class="o">(</span><span class="n">ComponentExecutorFactory</span><span
class="o">.</span><span class="na">class</span><span class="o">.</span><span
class="na">getName</span><span class="o">(),</span> <span
class="kc">null</span><span class="o">)</span>
+ <span class="o">.</span><span
class="na">setImplementation</span><span class="o">(</span><span
class="n">ComponentExecutorFactoryImpl</span><span class="o">.</span><span
class="na">class</span><span class="o">)</span>
+ <span class="o">.</span><span class="na">add</span><span
class="o">(</span><span class="n">createConfigurationDependency</span><span
class="o">()</span>
+ <span class="o">.</span><span class="na">setPid</span><span
class="o">(</span><span
class="s">"com.acme.management.threadpool.ComponentExecutorFactoryImpl"</span><span
class="o">)));</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And here is the implementation for our ComponentExecutorFactory:</p>
+<div class="codehilite"><pre> <span class="n">package</span> <span
class="n">com</span><span class="p">.</span><span class="n">acme</span><span
class="p">.</span><span class="n">management</span><span
class="p">.</span><span class="n">threadpool</span><span class="p">;</span>
+ <span class="n">import</span> <span class="n">org</span><span
class="p">.</span><span class="n">apache</span><span class="p">.</span><span
class="n">felix</span><span class="p">.</span><span class="n">dm</span><span
class="o">.*</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">class</span> <span
class="n">ComponentExecutorFactoryImpl</span> <span class="n">implements</span>
<span class="n">ComponentExecutorFactory</span> <span class="p">{</span>
+ <span class="n">volatile</span> <span class="n">Executor</span> <span
class="n">m_threadPool</span><span class="p">;</span>
+
+ <span class="n">void</span> <span class="n">updated</span><span
class="p">(</span><span class="n">Dictionary</span> <span
class="n">conf</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">m_sharedThreadPool</span> <span class="p">=</span>
<span class="n">Executors</span><span class="p">.</span><span
class="n">newFixedThreadPool</span><span class="p">(</span><span
class="n">Integer</span><span class="p">.</span><span
class="n">parseInt</span><span class="p">(</span>"<span
class="n">threadpool</span><span class="p">.</span><span
class="nb">size</span>"<span class="p">));</span>
+ <span class="p">}</span>
+
+ <span class="p">@</span><span class="n">Override</span>
+ <span class="n">public</span> <span class="n">Executor</span> <span
class="n">getExecutorFor</span><span class="p">(</span><span
class="n">Component</span> <span class="n">component</span><span
class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span
class="n">m_sharedThreadPool</span><span class="p">;</span> <span
class="o">//</span> <span class="n">Use</span> <span class="n">a</span> <span
class="n">shared</span> <span class="n">threadpool</span> <span
class="k">for</span> <span class="n">all</span> <span
class="n">Components</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+</pre></div>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1665336 by pderop on Mon, 9 Mar 2015 20:11:01 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
