You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2018/10/31 10:11:15 UTC
[camel] branch master updated (c008810 -> 4a885bf)
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git.
from c008810 Added Service Pool to Summary
new 0177dd2 Added Threading Model to Docs
new 4a885bf Added Threading Model to Summary
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/user-manual/en/SUMMARY.md | 2 +-
docs/user-manual/en/threading-model.adoc | 244 +++++++++++++++++++++++++++++++
2 files changed, 245 insertions(+), 1 deletion(-)
create mode 100644 docs/user-manual/en/threading-model.adoc
[camel] 01/02: Added Threading Model to Docs
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 0177dd262167e2fda3661e80b00beaaa1237f3db
Author: Andrea Cosentino <an...@gmail.com>
AuthorDate: Wed Oct 31 11:09:30 2018 +0100
Added Threading Model to Docs
---
docs/user-manual/en/threading-model.adoc | 244 +++++++++++++++++++++++++++++++
1 file changed, 244 insertions(+)
diff --git a/docs/user-manual/en/threading-model.adoc b/docs/user-manual/en/threading-model.adoc
new file mode 100644
index 0000000..888f179
--- /dev/null
+++ b/docs/user-manual/en/threading-model.adoc
@@ -0,0 +1,244 @@
+[[ThreadingModel-ThreadingModel]]
+=== Threading Model
+
+*Available as of Camel 2.3*
+
+The threading model in Camel is based on leveraging the JDK concurrency
+API which provides thread pools, named `ExecutorService`.
+
+Camel leverages thread pools in the following places:
+
+* several link:eip.html[EIP] patterns supports using thread pools for
+concurrency
+* link:seda.html[SEDA] component for asynchronous connectivity
+* link:async.html[Threads DSL] in the Camel route
+* link:servicepool.html[ServicePool] for pooling services
+* And some component provide thread pools by nature such as
+link:jms.html[JMS], link:jetty.html[Jetty]
+
+[[ThreadingModel-Threadpoolprofiles]]
+==== Thread pool profiles
+
+By default when a thread pool is to be created then its based on the
+default thread pool profile which is:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------
+ <threadPoolProfile id="defaultThreadPoolProfile" defaultProfile="true"
+ poolSize="10" maxPoolSize="20" maxQueueSize="1000" allowCoreThreadTimeOut="false"
+ rejectedPolicy="CallerRuns"/>
+--------------------------------------------------------------------------------------------------------
+
+What that means is that for example when you use
+link:multicast.html[Multicast] with `parallelProcessing=true` enabled,
+then it would create a thread pool based on the profile above. The
+`rejectedPolicy` has four options:
+`Abort, CallerRuns, Discard, DiscardOldest` which corresponds to the
+same four options provided out of the box in the JDK.
+*Notice:* option allowCoreThreadTimeOut is a new option from *Camel
+2.15* onwards.
+
+You can define as many thread pool profiles as you like. But there must
+only *one* default profile. A custom thread pool profile will inherit
+from the default profile. Which means that any option you do not
+explicit define will fallback and use the option from the default
+profile.
+
+You can use `-1` in maxQueueSize to indicate a unbounded queue.
+
+In Java DSL you can configure the default thread pool profile from the
+`ExecutorServiceStrategy`/`ExecutorServiceManager` which you access from
+`CamelContext`.
+
+[[ThreadingModel-Usingthreadpoolprofiles]]
+==== Using thread pool profiles
+
+Suppose you want to use a custom thread pool profile for a Multicast EIP
+pattern in a Camel route you can do it using the `executorServiceRef`
+attribute as shown:
+
+[source,java]
+---------------------------------------------------------------------------
+<camelContext ...>
+ ...
+ <threadPoolProfile id="fooProfile"
+ poolSize="20" maxPoolSize="50" maxQueueSize="-1"/>
+ ...
+
+ <route>
+ ...
+ <multicast strategyRef="myStrategy" executorServiceRef="fooProfile">
+ ...
+ </multicast>
+ ...
+ <route>
+</camelContext>
+---------------------------------------------------------------------------
+
+What Camel will do at runtime is to lookup in the
+link:registry.html[Registry] for a `ExecutorService` with the id =
+fooProfile. If none found it will fallback and see if there is a
+`ThreadPoolProfile` defined with that id. And in this example there is
+and so the profile is used for creating a new `ExecutorService` which is
+handed back to the link:multicast.html[Multicast] EIP to use in the
+route.
+
+[[ThreadingModel-Createcustomthreadpool]]
+==== Create custom thread pool
+
+You can also use the <threadPool/> tag in Spring XML to create a
+specific thread pool (eg `ExecutorService`). Notice that any options you
+do not explicit define, will have Camel to use the default thread pool
+profile as fallback. For example if you omit setting the `maxQueueSize`
+then Camel will fallback and use the value from the default thread pool
+profiles, which by default is 1000.
+
+[[ThreadingModel-Management]]
+==== Management
+
+All the thread pools that Camel creates are managed and thus you can see
+them in JConsole under the `threadpools` category.
+
+[[ThreadingModel-ExecutorServiceStrategy]]
+==== ExecutorServiceStrategy
+
+*Available as of Camel 2.3 to 2.8.x* +
+ Camel provides a pluggable strategy to hook in your own thread pool
+provider, for example from a WorkManager in a J2EE server etc. +
+ See the `org.apache.camel.spi.ExecutorServiceStrategy` interface which
+you should implement and hook into the WorkManager.
+
+See
+link:advanced-configuration-of-camelcontext-using-spring.html[Advanced
+configuration of CamelContext using Spring] for how to configure it.
+
+You can configure it on the `CamelContext` from Java DSL using the
+getter/setter.
+
+[[ThreadingModel-ExecutorServiceManager]]
+==== ExecutorServiceManager
+
+*Available as of Camel 2.9*
+
+In camel 2.9.0 the `ExecutorServiceManager` replaces the
+`ExecutorServiceStrategy`. It is renamed to manager as is not only
+provides a strategy for thread pool creation but also keeps track of
+thread pools and thread pool profiles.
+
+To hook in custom thread pool providers (e.g. for J2EE servers) a
+`ThreadPoolFactory` interface can be implemented. The implementation can
+be set in the `ExecutorServiceManager`. The Factory interface is much
+simpler then the former `ExecutorServiceStrategy` and makes the job of
+integrators much easier.
+
+See
+link:advanced-configuration-of-camelcontext-using-spring.html[Advanced
+configuration of CamelContext using Spring] for how to configure it.
+
+[[ThreadingModel-Customizingthreadnames]]
+==== Customizing thread names
+
+On the `ExecutorServiceStrategy`/`ExecutorServiceManager` you can
+configure the thread name pattern using the `setThreadNamePattern`
+method, which defines the thread names used when a thread pool creates a
+thread.
+
+The default pattern is for:
+
+* *Camel 2.9.x or older:*
+`Camel (${camelId}) thread #${counter} - ${name`}
+* *Camel 2.10 onwards:* `Camel (#camelId#) thread ##counter# - #name#`
+
+Notice we renamed the tokens from Camel 2.10 onwards to not clash with
+tokens by the link:using-propertyplaceholder.html[Property Placeholder].
+
+In the pattern you can use the following placeholders
+
+* $\{camelId} *Camel 2.6:* is the link:camelcontext.html[CamelContext]
+name
+* $\{counter} is a unique incrementing counter.
+* $\{name} is the regular thread name.
+* $\{longName} is the long thread name which can includes endpoint
+parameters etc.
+
+Notice the pattern name has changed from Camel 2.10 onwards, use #name#
+instead.
+
+In Camel 2.11 onwards its easier to set the thread name pattern on the
+CamelContext using the threadNamePattern attribute in the XML files as
+shown below:
+
+[source,java]
+--------------------------------------------------------------------------------------------------------------
+ <camelContext xmlns="http://camel.apache.org/schema/spring" threadNamePattern="Riding the thread #counter#">
+ <route>
+ <from uri="seda:start"/>
+ <to uri="log:result"/>
+ <to uri="mock:result"/>
+ </route>
+ </camelContext>
+--------------------------------------------------------------------------------------------------------------
+
+[[ThreadingModel-Componentdevelopers]]
+==== Component developers
+
+If you develop your own Camel component and are in need of a thread
+pool, then its advised to use the
+`ExecutorServiceStrategy`/`ExecutorServiceManager` to create the thread
+pool you need.
+
+[[ThreadingModel-Shutdown]]
+==== Shutdown
+
+All thread pools created by Camel will be properly shutdown when
+`CamelContext` shutdowns which ensures no leaks in the pools in case you
+run in a server environment with hot deployments and the likes.
+
+The `ExecutorServiceManager` has APIs for shutting down thread pools
+graceful and aggressively. Its encourage to use this API for creating
+and shutting down thread pools.
+
+From *Camel 2.11* onwards Camel the graceful
+`shutdownGraceful(executorService)` method from `ExecutorServiceManager`
+will shutdown graceful at first, until a timeout value is hit. After
+that it shutdown aggressively, again using the timeout value to wait for
+the operation to complete. This means you can wait at most 2 x timeout
+for shutting down the thread pool. +
+ The timeout value is by default `10000` millis. You can configure a
+custom value on the `ExecutorServiceManager` if needed. During shutdown
+Camel will log every 2nd second at INFO level progress of shutting down
+the thread pool. For example in case a shutdown takes a while, then
+there is activity in the logs.
+
+The APIs on `ExecutorServiceManager` that is related to shutting down a
+thread pool is as follows:
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+|Method |Description
+
+|shutdown |Marks the thread pool as shutdown, eg just as calling
+`ExecutorService.shutdown()` method
+
+|shutdownNow |Forces the thread pool to shutdown now, eg just as calling
+`ExecutorService.shutdownNow()` method
+
+|shutdownGraceful |*Camel 2.11:* Marks the thread pool as shutdown, and graceful shutdown
+the pool, by waiting for tasks to complete. A default timeout value of
+10 sec is used, before
+ shutdown becomes aggressive using `shutdownNow`, to force threads to
+shutdown.
+
+|shutdownGraceful(timeout) |*Camel 2.11:* As above but with custom timeout value
+
+|awaitTermination |*Camel 2.11:* To wait graceful for the termination of a thread pool (eg
+to wait for its tasks to complete). Will wait until all tasks is
+completed or a timeout value is hit.
+|===
+
+[[ThreadingModel-SeeAlso]]
+==== See Also
+
+* link:architecture.html[Architecture]
+* link:async.html[Async]
+
[camel] 02/02: Added Threading Model to Summary
Posted by ac...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 4a885bf531edadd95a1a3cc4ab965436bebb35a7
Author: Andrea Cosentino <an...@gmail.com>
AuthorDate: Wed Oct 31 11:10:52 2018 +0100
Added Threading Model to Summary
---
docs/user-manual/en/SUMMARY.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index ec27d11..ecc4f2d 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -115,7 +115,7 @@
* [Routes](routes.adoc)
* [ServicePool](servicepool.adoc)
* Stream caching
-* Threading Model
+* [Threading Model](threading-model.adoc)
* ToAsync
* Tracer
* [Transport](transport.adoc)