Bug 59229

Summary: Wrong documentation: NIO connector is non-blocking when reading http request
Product: Tomcat 7 Reporter: Huxing Zhang <huxing.zhang>
Component: DocumentationAssignee: Tomcat Developers Mailing List <dev>
Status: RESOLVED FIXED    
Severity: major    
Priority: P2    
Version: trunk   
Target Milestone: ---   
Hardware: All   
OS: All   
Attachments: Patch to fix the wrong description about NIO connector
Patch to fix the wrong description about HTTP/AJP NIO connector

Description Huxing Zhang 2016-03-24 05:57:53 UTC
https://tomcat.apache.org/tomcat-7.0-doc/config/http.html

It says NIO connector is blocking for reading http request, actually it is non-blocking.
Comment 1 Christopher Schultz 2016-03-24 12:52:49 UTC
This used to be described as "sim-blocking" but evidently that caused confusion.

Because the servlet API is stream-based, the behavior of request/response read/write is always effectively "blocking" -- at least as far as the application is concerned. The request-processing thread will be tied-up waiting for the read/write request to complete before returning to the servlet.

So even though non-blocking IO is being used under the covers, the application isn't using a non-blocking API to make IO requests. That's why the description is "blocking" in that table.
Comment 2 Huxing Zhang 2016-03-24 13:00:05 UTC
Hi,

I understand what you mean, but the following documentation are all saying that NIO connector is Non-blocking when reading request:

https://tomcat.apache.org/tomcat-9.0-doc/config/http.html
https://tomcat.apache.org/tomcat-8.0-doc/config/http.html
https://tomcat.apache.org/tomcat-6.0-doc/config/http.html

At least they should keep consistent.
Comment 3 Christopher Schultz 2016-03-24 13:08:55 UTC
Aah, yes, sorry. I didn't read the description carefully enough. Specifically, reading the "Request" (that is, specifically, the request-line of the HTTP request) is in fact non-blocking. I think that extends to the HTTP headers as well.

But it doesn't extend to the request body.
Comment 4 Huxing Zhang 2016-03-24 13:14:21 UTC
Yes, I mean the description is wrong about non-blocking for reading http request line (request header).
Comment 5 Huxing Zhang 2016-03-24 13:37:17 UTC
Created attachment 33703 [details]
Patch to fix the wrong description about NIO connector
Comment 6 Huxing Zhang 2016-03-24 13:50:04 UTC
This seems to be a regression, which is introduced by the following commit:

https://github.com/apache/tomcat70/commit/b0b4cfff188c5fe4d5a78ea995a1ace3a72f6c65

Oh I forgot the AJP part in my patch, will update it later.
Comment 7 Huxing Zhang 2016-03-24 13:53:54 UTC
Created attachment 33704 [details]
Patch to fix the wrong description about HTTP/AJP NIO connector
Comment 8 Huxing Zhang 2016-03-24 14:00:05 UTC
I think the documentation in AJP is more clear. In webapps/docs/config/ajp.xml it says,  "Read Request Headers" is Non Blocking. In webapps/docs/config/http.xml it says, "Read HTTP Request" is Non Blocking. HTTP Request includes header and body, so I think specifying "Read HTTP Request Headers" is more accurate.
Comment 9 Mark Thomas 2016-03-30 11:02:16 UTC
Thanks for the report and for digging out the commit that introduced the error.

Note: AJP IS blocking for all connectors for Request Headers and Request Bodies.

I've corrected the HTTP docs for 7.0.x and improved the row titles for 7.0x through 9.0.x.
Comment 10 Huxing Zhang 2016-03-31 00:19:31 UTC
Thanks for clarifying AJP is blocking for NIO connector for reading http headers and request. 
My bad not digging into the AJP code. I will take care from next time.