Advanced IO and Tomcat

Return-Path: Delivered-To: apmail-tomcat-dev-archive@www.apache.org Received: (qmail 31886 invoked from network); 7 Jun 2007 12:15:50 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 7 Jun 2007 12:15:50 -0000 Received: (qmail 10962 invoked by uid 500); 7 Jun 2007 12:15:50 -0000 Delivered-To: apmail-tomcat-dev-archive@tomcat.apache.org Received: (qmail 10680 invoked by uid 500); 7 Jun 2007 12:15:48 -0000 Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Tomcat Developers List" Delivered-To: mailing list dev@tomcat.apache.org Received: (qmail 10669 invoked by uid 500); 7 Jun 2007 12:15:48 -0000 Delivered-To: apmail-jakarta-tomcat-dev@jakarta.apache.org Received: (qmail 10666 invoked by uid 99); 7 Jun 2007 12:15:48 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 Jun 2007 05:15:48 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 07 Jun 2007 05:15:44 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id BA90E1A981D; Thu, 7 Jun 2007 05:15:23 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r545151 - in /tomcat/trunk: java/org/apache/catalina/CometEvent.java java/org/apache/catalina/CometProcessor.java java/org/apache/catalina/connector/CometEventImpl.java webapps/docs/aio.xml Date: Thu, 07 Jun 2007 12:15:23 -0000 To: tomcat-dev@jakarta.apache.org From: fhanik@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070607121523.BA90E1A981D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: fhanik Date: Thu Jun 7 05:15:22 2007 New Revision: 545151 URL: http://svn.apache.org/viewvc?view=rev&rev=545151 Log: Simplified the API, no need for the IOExceptions Updated documentation, added in some notes about life cycle, more source code examples to come Modified: tomcat/trunk/java/org/apache/catalina/CometEvent.java tomcat/trunk/java/org/apache/catalina/CometProcessor.java tomcat/trunk/java/org/apache/catalina/connector/CometEventImpl.java tomcat/trunk/webapps/docs/aio.xml Modified: tomcat/trunk/java/org/apache/catalina/CometEvent.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/CometEvent.java?view=diff&rev=545151&r1=545150&r2=545151 ============================================================================== --- tomcat/trunk/java/org/apache/catalina/CometEvent.java (original) +++ tomcat/trunk/java/org/apache/catalina/CometEvent.java Thu Jun 7 05:15:22 2007 @@ -26,7 +26,9 @@ /** * The CometEvent interface. + * A comet event is the contract between the servlet container and the servlet implementation(CometProcessor) for handling comet connections. * + * @see CometProcessor * @author Filip Hanik * @author Remy Maucherat */ @@ -174,14 +176,14 @@ * Tomcat Comet allows you to configure for additional options:
* the COMET_NON_BLOCKING bit signals whether writing and reading from the request * or writing to the response will be non blocking.
- * the COMET_NO_IO bit signals the container that you are not interested in - * receiving any IO events from the container. - * @param cometOptions int - the option bit set, see #COMET_NON_BLOCKING and #COMET_NO_IO - * @throws IOException - + * the COMET_BLOCKING bit signals the container you wish for read and write to be done in a blocking fashion + * @param cometOptions int - the option bit set * @throws IllegalStateException - if this method is invoked outside of the BEGIN event + * @see #CometConfiguration + * @see #isReadable() + * @see #isWriteable() */ - public void configure(CometConfiguration... options) - throws IOException, IllegalStateException; + public void configure(CometConfiguration... options) throws IllegalStateException; /** * Returns the configuration for this Comet connection @@ -202,21 +204,17 @@ * Registers the Comet connection with the container for IO notifications. * These could be notifications * @param operations - * @throws IOException * @throws IllegalStateException - if you are trying to register with a socket that already is registered * or if the operation you are trying to register is invalid. */ - public void register(CometOperation... operations) - throws IOException, IllegalStateException; + public void register(CometOperation... operations) throws IllegalStateException; /** * Unregisters Comet operations for this CometConnection * @param operations CometOperation[] - * @throws IOException * @throws IllegalStateException */ - public void unregister(CometOperation... operations) - throws IOException, IllegalStateException; + public void unregister(CometOperation... operations) throws IllegalStateException; /** * Returns what the current IO notifications that the Comet Modified: tomcat/trunk/java/org/apache/catalina/CometProcessor.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/CometProcessor.java?view=diff&rev=545151&r1=545150&r2=545151 ============================================================================== --- tomcat/trunk/java/org/apache/catalina/CometProcessor.java (original) +++ tomcat/trunk/java/org/apache/catalina/CometProcessor.java Thu Jun 7 05:15:22 2007 @@ -28,7 +28,17 @@ * asynchronous IO, recieving events when data is available for reading, and * being able to output data without the need for being invoked by the container. * Note: When this interface is implemented, the service method of the servlet will - * never be called, and will be replaced with a begin event. + * never be called, and will be replaced with a begin event. Should the connector you + * have configured not support Comet, the service method will be called, and the + * request/response will not be marked as comet, but instead behave like a regular + * Servlet
+ * + * A Comet request, aka Comet connection, referenced through the #CometEvent and the request/response pair + * and has a lifecycle somewhat different to a regular servlet.
+ * + * Read more about it in the Tomcat documentation about Advanced IO, + * + * */ public interface CometProcessor extends Servlet { Modified: tomcat/trunk/java/org/apache/catalina/connector/CometEventImpl.java URL: http://svn.apache.org/viewvc/tomcat/trunk/java/org/apache/catalina/connector/CometEventImpl.java?view=diff&rev=545151&r1=545150&r2=545151 ============================================================================== --- tomcat/trunk/java/org/apache/catalina/connector/CometEventImpl.java (original) +++ tomcat/trunk/java/org/apache/catalina/connector/CometEventImpl.java Thu Jun 7 05:15:22 2007 @@ -19,6 +19,7 @@ package org.apache.catalina.connector; import java.io.IOException; +import java.util.Arrays; import java.util.HashSet; import javax.servlet.ServletException; import javax.servlet.http.HttpServletRequest; @@ -28,8 +29,6 @@ import org.apache.catalina.util.StringManager; import org.apache.coyote.ActionCode; import org.apache.tomcat.util.net.PollerInterest; -import java.util.Arrays; -import org.apache.tomcat.util.MutableBoolean; public class CometEventImpl implements CometEvent { @@ -43,11 +42,8 @@ public CometEventImpl(Request request, Response response) { this.request = request; this.response = response; - try { - this.register(CometOperation.OP_READ); - }catch ( IOException x ) { - throw new IllegalStateException(x.getMessage(),x); - } + //default behavior is to only listen for read events + register(CometOperation.OP_READ); } @@ -99,6 +95,8 @@ public void clear() { request = null; response = null; + cometConfigurations.clear(); + cometOperations.clear(); } public void setEventType(EventType eventType) { @@ -153,8 +151,7 @@ return cometOperations.contains(op); } - public void configure(CometEvent.CometConfiguration... options) - throws IOException, IllegalStateException { + public void configure(CometEvent.CometConfiguration... options) throws IllegalStateException { checkWorkerThread(); cometConfigurations.clear(); for (CometEvent.CometConfiguration cc : options) { @@ -163,15 +160,13 @@ request.action(ActionCode.ACTION_COMET_CONFIGURE,options); } - public void register(CometEvent.CometOperation... operations) - throws IOException, IllegalStateException { + public void register(CometEvent.CometOperation... operations) throws IllegalStateException { //add it to the registered set cometOperations.addAll(Arrays.asList(operations)); request.action(ActionCode.ACTION_COMET_REGISTER, translate(cometOperations.toArray(new CometOperation[0]))); } - public void unregister(CometOperation... operations) - throws IOException, IllegalStateException { + public void unregister(CometOperation... operations) throws IllegalStateException { //remove from the registered set cometOperations.removeAll(Arrays.asList(operations)); request.action(ActionCode.ACTION_COMET_REGISTER, translate(cometOperations.toArray(new CometOperation[0]))); Modified: tomcat/trunk/webapps/docs/aio.xml URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/aio.xml?view=diff&rev=545151&r1=545150&r2=545151 ============================================================================== --- tomcat/trunk/webapps/docs/aio.xml (original) +++ tomcat/trunk/webapps/docs/aio.xml Thu Jun 7 05:15:22 2007 @@ -9,6 +9,7 @@ Advanced IO and Tomcat Remy Maucherat + Filip Hanik @@ -39,6 +40,118 @@ other source).

+ +

+ Comet Connection - For the readability of this document we will be referring an open ended HTTP request and an open + ended HTTP response that are mapped to a Cometprocessor as a "Comet Connection". +

+ Comet Processor - a servlet that implements the org.apache.catalina.CometProcessor interface. + Used to process comet connections and the events on the connection +

+ Comet Event - an event triggered by the container related to a Comet Connection +

+ Open Ended Request - a HTTP request that is either chunked or has a very large content length, allowing + data to be sent at different times. This is how Tomcat gets around the request/response methodology of + the HTTP protocol allowing Comet Processors to send and receive data on the socket synchronously and asynchronously. +

+ Open Ended Response - see Open Ended Request +

+ Active Comet Connection, a comet connection that currently is associated with a TCP connection and an open ended request/response. +

+ Blocking Comet Connection, an invocation of the read/write methods will block until data was received/sent. +

+ Non blocking Comet Connection, an invocation of the read/write methods will not block. +

+ Comet operation - comet connections can register themselves for a set of events to be + notified of. The different operations are:
+ OP_READ - results in a READ event when data has been received
+ OP_WRITE - results in a WRITE event when the socket is ready to receive data
+ OP_CALLBACK - results in a CALLBACK event on a Tomcat thread. +

+ Connection Centric - Comet connections are based on actual IO events on a TCP connection from the TCP layer. + This is different from servlets that are based on HTTP requests and responses, by the HTTP protocol above the TCP layer. +

+ Closing a comet connection - may not actually mean that the underlying TCP connection is closed. Tomcat still + respects the maxKeepAliveRequests attribute of the connector, and may decide to keep the connection + open. This is the case in the event of a connection timeout, the event ERROR/TIMEOUT is signaled and the + TCP connection is reused for the next HTTP request. +

+ + + +

+ The lifecycle and event cycle of a Comet Connection is slightly different than a regular servlet. + Instead the life/event cycle is very "connection centric" and based on IO events, rater then + a request/response cycle like a normal HTTP request. This is the most common mistake developers make when they + start writing comet servlets, is that they don't realize that it is all based around these different events, and + that the events are some what connection centric. +

+ A comet interaction is started by the container invoking the event method on the Comet Processor + and the event will have a BEGIN type. For a deeper explanation of types, keep reading. + Once a BEGIN event has been invoked, the Comet Connection is active. At this type, the Comet Event object + reference can be used to reference the HttpServletRequest/HttpServletResponse objects for asynchronous actions + such as reading or writing from the streams or readers/writers. At this point the comet connection is considered active + or initiated. +

+ Once the Comet connection is active, the comet processor will receive events from the container. + These events are defined in the section below.
+ A comet processor may register itself for events, and receive the events when they happen. + In a similar fashion, a comet processor may unregister itself from comet events and + use the isReadable/isWriteable methods on the comet event to detect the state + of the comet connection. The registered events will be in effect until they are unregistered, + the comet connection is closed or terminated. + By default a comet connection gets registered for READ events upon initiation. +
+ The event registration can be compared to poll or select structures of different operating systems, + and also bear some resemblances with the java.nio API. +

+ Since Comet Connections deal directly with the IO layer of the container/connection and read and writes can be done + asynchronously, caution and care should be excersized when programming this. the comet connection itself is not thread safe + as such an implementation would suffer performance issues, instead it is up to the comet processor developer to ensure that + thread safety is reached and properly handled. + As an example, registering the comet connection for READ events and at the same time performing asynchronous reads + on the input stream or the reader, can cause data corruption and dead locks. + Same way, using multiple threads to do writes to the output stream or writer can have the same effect. +
To be thread safe, one can synchronize on the event object, but you will also need to coordinate it with + events that are registered. +

+ There is an event that is not IO based, that is the CometEvent.EventType.CALLBACK event. + This is an event that is forced by Tomcat when the OP_CALLBACK operation is registered. + Using the OP_CALLBACK operation, Tomcat will spawn a Tomcat worker thread that you can use to piggy back + on for reading/writing data or performing other operations, and not having to have spawn and synchronize + your own background threads.
+ An example scenarion would be where you have one thread pulling content for different comet clients. + When the background thread has content for a client, it can store it in the request object as an attribute, + then register for the OP_CALLBACK event. Once the CALLBACK event, then the application can use Tomcat's worker + thread to write the data to the client.
+ Tomcat guarantees that only one thread will be invoking the CometProcessor event for a particular client, + so by using the Tomcat worker threads to perform your actions, you are thread safe without the expense of + locks or synchronized methods.
+ Another usage scenario for the CALLBACK event, is when you close the comet connection asynchronously and you want + it processed by tomcat without depending on a timeout or another IO event. This would look like + + ... + event.close(); + event.register(CometEvent.CometOperation.OP_CALLBACK); + ... + +

+ +

@@ -55,42 +168,54 @@

EventType.BEGIN: will be called at the beginning of the processing of the connection. It can be used to initialize any relevant - fields using the request and response objects. Between the end of the processing + fields using the request and response objects. During the BEGIN event you may also configure + your comet connection for blocking or non blocking mode. using the configure + method on the comet event object. Between the end of the processing of this event, and the beginning of the processing of the end or error events, it is possible to use the response object to write data on the open connection. Note that the response object and depedent OutputStream and Writer are still not synchronized, so when they are accessed by multiple threads, synchronization is mandatory. After processing the initial event, the request - is considered to be committed.

EventType.READ: This indicates that input data is available, and that one read can be made - without blocking. The available and ready methods of the InputStream or - Reader may be used to determine if there is a risk of blocking: the servlet - should read while data is reported available, and can make one additional read - should read while data is reported available. When encountering a read error, - the servlet should report it by propagating the exception properly. Throwing - an exception will cause the error event to be invoked, and the connection - will be closed. - Alternately, it is also possible to catch any exception, perform clean up - on any data structure the servlet may be using, and using the close method - of the event. It is not allowed to attempt reading data from the request - object outside of the execution of this method.
- On some platforms, like Windows, a client disconnect is indicated by a READ event. - Reading from the stream may result in -1, an IOException or an EOFException. - Make sure you properly handle all these three cases. - If you don't catch the IOException, Tomcat will instantly invoke your event chain with an ERROR as - it catches the error for you, and you will be notified of the error at that time. + without blocking. The available() and ready() methods of the InputStream or + Reader may be used to determine if there is a risk of blocking: the servlet + should read while data is reported available, and can make one additional read + should read while data is reported available. Not reading all the data, is not recommended, + as it may lead to unexpected behavior depending on the connector implementation.
+ When encountering a read error, the servlet should report it by propagating the exception properly. + Throwing an exception will cause the error event to be invoked, and the connection + will be closed.
+ Alternately, it is also possible to catch any exception, perform clean up + on any data structure the servlet may be using, and using the close() method + of the event object. It is not recommended to attempt reading data from the request + object outside of the execution of this method/event if the comet connection is registered for + the READ event. Instead unregister the read event to perform asynchronous reads.
+ On some platforms, like Windows, a client disconnect is indicated by a READ event. + Reading from the stream may result in -1, an IOException or an EOFException. + Make sure you properly handle all these three cases. + If you don't catch the IOException, Tomcat will instantly invoke your event chain with an ERROR as + it catches the error for you, and you will be notified of the error at that time.

+
EventType.WRITE: If you wish to be notified whether you can write data to the underlying TCP socket, + register your comet connection for this event. Tomcat will invoke this event, and you can write to the response + object. This event is not needed nor should be used unless you are running the comet connection in non blocking mode.

+
EventType.CALLBACK: When a comet connection is registered using the OP_CALLBACK operation, + Tomcat will generate the CALLBACK event periodically. The CALLBACK will always + be invoked using a Tomcat worker thread, just like the other event types.
EventType.END: End may be called to end the processing of the request. Fields that have been initialized in the begin method should be reset. After this event has been processed, the request and response objects, as well as all their dependent objects will be recycled and used to process other requests. End will also be called when data is available and the end of file is reached on the request input - (this usually indicates the client has pipelined a request).

EventType.ERROR: Error will be called by the container in the case where an IO exception or a similar unrecoverable error occurs on the connection. Fields that have been initialized in the begin method should be reset. After this event has been processed, the request and response objects, as well as all their dependent - objects will be recycled and used to process other requests.

@@ -284,11 +409,12 @@

If you are using the NIO connector, you can set individual timeouts for your different comet connections. To set a timeout, simple set a request attribute like the following code shows: - CometEvent event.... event.setTimeout(30*1000); or - event.getHttpServletRequest().setAttribute("org.apache.tomcat.comet.timeout", new Integer(30 * 1000)); - This sets the timeout to 30 seconds. - Important note, in order to set this timeout, it has to be done on the BEGIN event. - The default value is soTimeout + CometEvent event.... event.setTimeout(30*1000); +
You can set the timeout on the comet connection at any point in time, even asynchronously. + Setting a timeout to 1 (one milliseconds) doesn't guarantee that it will timeout at that time. + Setting the timeout gurantees that Tomcat wont timeout the connection before the connection has been idle + for the configured time. The time it actually times out depends on many factors, such as how busy the server is, + when the last timeout scan was run, etc., but generally a timeout will occur fairly close to its configured value.

If you are using the APR connector, all Comet connections will have the same timeout value. It is soTimeout*50

--------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org For additional commands, e-mail: dev-help@tomcat.apache.org