Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1969:275c928ab386

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
The HTTP request finalization section of the development guide.
author Roman Arutyunyan <arut@nginx.com>
date Wed, 19 Apr 2017 18:36:37 +0300
parents 69908bd68481
children a1d29eda04b6
comparison
equal deleted inserted replaced
1968:69908bd68481 1969:275c928ab386
4979 <literal>header_only</literal> flag is set. 4979 <literal>header_only</literal> flag is set.
4980 This prevents subrequest body from being sent to the client. 4980 This prevents subrequest body from being sent to the client.
4981 Its header is ignored anyway. 4981 Its header is ignored anyway.
4982 The result of the subrequest can be analyzed in the callback handler. 4982 The result of the subrequest can be analyzed in the callback handler.
4983 </para> 4983 </para>
4984
4985 </section>
4986
4987
4988 <section name="Request finalization" id="http_request_finalization">
4989
4990 <para>
4991 An HTTP request is finalized by calling the function
4992 <literal>ngx_http_finalize_request(r, rc)</literal>.
4993 It is usually finalized by the content handler after sending all output buffers
4994 to the filter chain.
4995 At this point the output may not be completely sent to the client, but remain
4996 buffered somewhere along the filter chain.
4997 If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function will
4998 automatically install a special handler <literal>ngx_http_writer(r)</literal>
4999 to finish sending the output.
5000 A request is also finalized in case of an error or if a standard HTTP response
5001 code needs to be returned to the client.
5002 </para>
5003
5004 <para>
5005 The function <literal>ngx_http_finalize_request(r, rc)</literal> expects the
5006 following <literal>rc</literal> values:
5007 </para>
5008
5009 <list type="bullet">
5010
5011 <listitem>
5012 <literal>NGX_DONE</literal> - fast finalization.
5013 Decrement request <literal>count</literal> and destroy the request if it
5014 reaches zero.
5015 The client connection may still be used for more requests after that
5016 </listitem>
5017
5018 <listitem>
5019 <literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
5020 (408), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal> (499) - error
5021 finalization.
5022 Terminate the request as soon as possible and close the client connection.
5023 </listitem>
5024
5025 <listitem>
5026 <literal>NGX_HTTP_CREATED</literal> (201),
5027 <literal>NGX_HTTP_NO_CONTENT</literal> (204), codes greater than or equal to
5028 <literal>NGX_HTTP_SPECIAL_RESPONSE</literal> (300) - special response
5029 finalization.
5030 For these values nginx either sends a default code response page to the client
5031 or performs the internal redirect to an
5032 <link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if it's
5033 configured for the code
5034 </listitem>
5035
5036 <listitem>
5037 Other codes are considered success finalization codes and may activate the
5038 request writer to finish sending the response body.
5039 Once body is completely sent, request <literal>count</literal> is decremented.
5040 If it reaches zero, the request is destroyed, but the client connection may
5041 still be used for other requests.
5042 If <literal>count</literal> is positive, there are unfinished activities
5043 within the request, which will be finalized at a later point.
5044 </listitem>
5045
5046 </list>
4984 5047
4985 </section> 5048 </section>
4986 5049
4987 5050
4988 <section name="Response" id="http_response"> 5051 <section name="Response" id="http_response">