From 51801317cc55f33b92834a532c52bcd8d9d4f118 Mon Sep 17 00:00:00 2001
From: Oleg Zhurakousky <ozhurakousky@vmware.com>
Date: Mon, 20 Sep 2010 14:36:30 -0400
Subject: [PATCH] INT-1450 Asynchronous polling section was added to Message
 Endpoints section of the ref manual

---
 src/docbkx/endpoint.xml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/docbkx/endpoint.xml b/src/docbkx/endpoint.xml
index 9974574a4c..21b69c4abe 100644
--- a/src/docbkx/endpoint.xml
+++ b/src/docbkx/endpoint.xml
@@ -310,4 +310,41 @@ any transaction configuration essentially allowing you to enhance the behavior o
 	</int:converter>]]></programlisting>
      </para>
   </section>
+  <section id="async-polling">
+    <title>Asynchronous polling</title>
+     <para>
+     If you want the polling to be asynchronous, Poller can optionaly specify 'task-executor' attribute 
+     pointing to an existing instance of <classname>TaskExecutor</classname> bean 
+     (Spring 3.0 provides a convinient namespaces configuration via the <code>task</code> namespace). However, there are certain things 
+     you must understand when configuring Poller with TaskExecutor. 
+     </para>
+     <para>
+     The problem is that there are two configurations in place. The <emphasis>Poller</emphasis> and the <emphasis>TaskExecutor</emphasis> 
+     and they both have to be in tune with each other otherwise you might end up creating an artificial memory leak. 
+     </para>
+     <para>
+     Let's look at the following configuration provided by one of the users on the Spring's 
+     forums (http://forum.springsource.org/showthread.php?t=94519):
+
+      <programlisting language="xml"><![CDATA[<int:service-activator input-channel="publishChannel" ref="myService">
+		<int:poller receive-timeout="5000" task-executor="taskExecutor" fixed-rate="50"/>
+</si:service-activator>
+	
+<task:executor id="taskExecutor" pool-size="20" queue-capacity="20"/>]]></programlisting>
+      
+	The above configuration demonstrates one of those out of tune configurations.
+     </para>
+     <para>
+     The poller keeps scheduling new tasks even though all the threads are blocked waiting for either a new message to arrive, 
+     or the timeout to expire. Given that there are 20 threads executing tasks with a 5 second timeout, they will be executed 
+     at a rate of 4 per second (5000/20 = 250ms). But, new tasks are being scheduled at a rate of 20 per second, so the internal 
+     queue in the task executor will grow at a rate of 16 per second (while the process is idle), so we essentially have a memory leak.
+     </para>
+     <para>
+     One of the ways to handle this is to set <code>queue-capacity</code> attribute of Task Executor to 0. You can also manage it by specifying what to do 
+     with messages that can not be queued up by setting <code>rejection-policy</code> attribute of Task Executor (e.g., DISCARD). In other 
+     words there are certain details you must understand with regard to configuring the TaskExecutor. Please refer 
+     to - <emphasis>Section 25 - Task Execution and Scheduling</emphasis> of Spring reference manual.
+     </para>
+  </section>
 </chapter>
\ No newline at end of file