From 0512ee1b6d050af1158460bebb458b810aca242c Mon Sep 17 00:00:00 2001 From: Ryan Bloom Date: Sat, 25 Mar 2000 15:45:01 +0000 Subject: [PATCH] Add docs for layered I/O git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@84838 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/index.html | 1 + docs/manual/developer/layeredio.html | 76 ++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/manual/developer/layeredio.html diff --git a/docs/manual/developer/index.html b/docs/manual/developer/index.html index a72dd44b21..e9b6d0509a 100644 --- a/docs/manual/developer/index.html +++ b/docs/manual/developer/index.html @@ -14,6 +14,7 @@

Developer Documentation for Apache-2.0

diff --git a/docs/manual/developer/layeredio.html b/docs/manual/developer/layeredio.html new file mode 100644 index 0000000000..d090e9dc02 --- /dev/null +++ b/docs/manual/developer/layeredio.html @@ -0,0 +1,76 @@ + + + +Apache 2.0 Layered I/O + + + + + +

Apache Layered I/O

+ +

Layered I/O has been the holy grail of Apache module writers for years. +With Apache 2.0, module writers can finally take advantage of layered I/O +in their modules. + +

In all previous versions of Apache, only one handler was allowed to modify +the data stream that was sent to the client. With Apache 2.0, one module +can modify the data and then specify that other modules can modify the data +if they would like. + +

Taking advantage of layered I/O

+ +

In order to make a module use layered I/O, there are some modifications +needed. A new return value has been added for modules, RERUN_HANDLERS. +When a handler returns this value, the core searches through the list of +handlers looking for another module that wants to try the request. + +

When a module returns RERUN_HANDLERS, it must modify teo fields of the +request_rec, the handler and content_type fields. Most modules will +set the handler field to NULL, and allow the core to choose the which +module gets run next. If these two fields are not modified, then the server +will loop forever calling the same module's handler. + +

Most module's should not write out to the network if they want to take +advantage of layered I/O. Two BUFF structures have been added to the +request_rec, one of input, and one for output. The module should read and +write to these BUFF's. The module will also have to setup the input field for +the next module in the list. A new function has been added, ap_setup_input, +which all modules should call before they do any reading to get data to modify. +This function checks to determine if the previous module set the input field, +if so, that input is used, if not the file is opend and that data source +is used. The output field is used basically the same way. The module must +set this field before they call ap_r* in order to take advantage of +layered I/O. If this field is not set, ap_r* will write directly to the +client. Usually at the end of a handler, the input (for the next module) +will be the read side of a pipe, and the output will be the write side of +the same pipe. + +

An Example of Layered I/O.

+ +

This example is the most basic layered I/O example possible. It is +basically CGI's generated by mod_cgi and sent to the network via http_core. + +

mod_cgi executes the cgi script, and then sets request_rec->input to +the output pipe of the CGI. It then NULL's out request_rec->handler, and +sets request_rec->content_type to whatever the CGI writes out (in this case, +text/html). Finally, mod_cgi returns RERUN_HANDLERS. + +

ap_invoke_handlers() then loops back to the top of the handler list +and searches for a handler that can deal with this content_type. In this case +the correct module is the default_handler from http_core. + +

When default handler starts, it calls ap_setup_input, which has found +a valid request_rec->input, so that is used for all inputs. The output field +in the request_rec is NULL, so when default_handler calls an output primitive +it gets sent out over the network.

+ +Ryan Bloom, 25th March 2000 + + -- 2.50.1