This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new a9dc99c CAMEL-16326: Add docs about exchange pooling
a9dc99c is described below
commit a9dc99c95034cc38a5a5642d6d324fbf4fad1a8c
Author: Claus Ibsen <claus.ib...@gmail.com>
AuthorDate: Fri Mar 12 11:14:45 2021 +0100
CAMEL-16326: Add docs about exchange pooling
---
docs/user-manual/modules/ROOT/nav.adoc | 1 +
.../modules/ROOT/pages/exchange-pooling.adoc | 81 ++++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/index.adoc | 1 +
3 files changed, 83 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index e736f36..2b0f340 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -61,6 +61,7 @@
** xref:dozer-type-conversion.adoc[Dozer Type Conversion]
** xref:endpoint-annotations.adoc[Endpoint Annotations]
** xref:exception-clause.adoc[Exception Clause]
+** xref:exchange-pooling.adoc[Exchange Pooling]
** xref:fluent-builders.adoc[Fluent Builders]
** xref:http-session-handling.adoc[HTTP-Session Handling]
** xref:parameter-binding-annotations.adoc[Parameter Binding Annotations]
diff --git a/docs/user-manual/modules/ROOT/pages/exchange-pooling.adoc
b/docs/user-manual/modules/ROOT/pages/exchange-pooling.adoc
new file mode 100644
index 0000000..d1643fb
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/exchange-pooling.adoc
@@ -0,0 +1,81 @@
+[[ExchangePooling-ExchangePooling]]
+= Exchange Pooling
+
+*Since Camel 3.9*
+
+Apache Camel requires a tiny resource overhead when routing message.
+
+For example the routing engine keeps state of each individual message, keeping
track of the message flow,
+and where messaging are going next. The routing engine also handles complex
tasks such as error handling,
+capturing metrics, and many other things. All together small numbers of Java
objects is allocated
+on the heap for each processing step during routing.
+
+With the advance of cloud computing, where work loads are precisely measured,
then Camel has undergone
+a series of core optimizations to reduce its overhead.
+
+== Pooling objects to reduce object allocations
+
+The _Exchange Pooling_ functionality is _object pooling_ by recycling commonly
used objects by the routing enginge.
+
+The most significant object being reused is the `org.apache.camel.Exchange`
object that is the root object
+that holds the message with its payload, headers, meta-data and other content.
+
+Besides pooling exchanges then internal objects used by the routing engine is
also pooled and recycled.
+All together this dramatically reduces the object allocations, from camel core
itself.
+
+There will always be objects allocations from the actual message content
(payload and headers), and also
+from the Camel components in use and its 3rd party libraries. The footprint of
Camel core and its routing engine is close to zero, when pooling is enabled.
+
+This all sounds marvelous so what is the negatives? Yes the price to pay for
object pooling,
+is the complexity of managing the pool (acquire and returning objects to the
pool); however
+all of this is taken care of by Camel itself. The object pools are using JDK
`ConcurrentMap`
+instances and take up very little memory. The negative is very tiny CPU cost
on adding and removing
+objects from the pools, and resetting the objects before reuse.
+
+It is possible better to sacrifice the very tiny CPU cost for reduced object
allocations, which helps
+to avoid the JVM garbage collection running more frequently, and causing your
application to halt or delay
+processing messages at any given time.
+
+== Enabling Exchange Pooling
+
+The _object pooling_ is currently not enabled by default, and requires to be
turned on.
+
+This can be done as shown in Java:
+
+[source,java]
+----
+CamelContext context = ...
+context.adapt(ExtendedCamelContext.class).setExchangeFactory(new
PooledExchangeFactory());
+----
+
+If using _Camel Main_, Camel Spring Boot, or Camel Quarkus
+you can enable this in the `application.properties`:
+
+[source,properties]
+----
+camel.main.exchange-factory = pooled
+----
+
+== Configuration Options
+
+The exchange pool can be configured with the following options:
+
+[width="100%",cols="25%,50%,25%",options="header"]
+|===
+|Option |Description | Default
+| exchange-factory | Whether to use pooling or not. Possible values are
prototype or pooled | prototype
+| exchange-factory-capacity | Maximum number of elemenets in the pool | 100
+| exchange-factory-statistics-enabled | Whether to capture usage statistics |
false
+|===
+
+== Management
+
+If object pooling is enabled, then Camel provides a JMX MBean which allows to
introspect the pools and its usage
+via JMX. This requires to add `camel-management` JAR to the classpath.
+
+== Examples
+
+We have provided a few examples which we are using for performance profiling.
+For example the basic `timer-log` example is on github at:
https://github.com/apache/camel-performance-tests/tree/master/profiling/timer-log
+
+
diff --git a/docs/user-manual/modules/ROOT/pages/index.adoc
b/docs/user-manual/modules/ROOT/pages/index.adoc
index 1baf367..e4c2301 100644
--- a/docs/user-manual/modules/ROOT/pages/index.adoc
+++ b/docs/user-manual/modules/ROOT/pages/index.adoc
@@ -101,6 +101,7 @@ camel routes without them knowing
* xref:error-handler.adoc[Error Handler]
* xref:exchange.adoc[Exchange]
* xref:exchange-pattern.adoc[Exchange Pattern]
+* xref:exchange-pooling.adoc[Exchange Pooling]
* xref:expression.adoc[Expression]
* xref:http-session-handling.adoc[HTTP-Session Handling]
* xref:injector.adoc[Injector]
