changeset 1436:2333e08e277d

Documented thread pools.
author Ruslan Ermilov <ru@nginx.com>
date Wed, 18 Mar 2015 19:01:42 +0300
parents 54ed6b72ad3b
children 8e7995bb8c6b
files xml/en/docs/http/ngx_http_core_module.xml xml/en/docs/ngx_core_module.xml xml/ru/docs/http/ngx_http_core_module.xml xml/ru/docs/ngx_core_module.xml
diffstat 4 files changed, 128 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_core_module.xml	Wed Mar 18 14:19:44 2015 +0000
+++ b/xml/en/docs/http/ngx_http_core_module.xml	Wed Mar 18 19:01:42 2015 +0300
@@ -17,7 +17,8 @@
 <directive name="aio">
 <syntax>
     <literal>on</literal> |
-    <literal>off</literal></syntax>
+    <literal>off</literal> |
+    <literal>threads</literal>[<literal>=</literal><value>pool</value>]</syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
@@ -118,6 +119,35 @@
 </para>
 
 <para>
+Finally, files can be read and <link id="sendfile">sent</link>
+using multi-threading (1.7.11),
+without blocking a worker process:
+<example>
+location /video/ {
+    sendfile       on;
+    aio            threads;
+}
+</example>
+Read and send file operations are offloaded to threads of the specified
+<link doc="../ngx_core_module.xml" id="thread_pool">pool</link>.
+If the pool name is omitted,
+the pool with the name “<literal>default</literal>” is used.
+The pool name can also be set with variables:
+<example>
+aio threads=pool$disk;
+</example>
+By default, multi-threading is disabled, it should be
+enabled with the
+<literal>--with-threads</literal> configuration parameter.
+Currently, multi-threading is compatible only with the
+<link doc="../events.xml" id="epoll"/>,
+<link doc="../events.xml" id="kqueue"/>,
+and
+<link doc="../events.xml" id="eventport"/> methods.
+Multi-threaded sending of files is only supported on Linux.
+</para>
+
+<para>
 See also the <link id="sendfile"/> directive.
 </para>
 
--- a/xml/en/docs/ngx_core_module.xml	Wed Mar 18 14:19:44 2015 +0000
+++ b/xml/en/docs/ngx_core_module.xml	Wed Mar 18 19:01:42 2015 +0300
@@ -397,6 +397,39 @@
 </directive>
 
 
+<directive name="thread_pool">
+<syntax>
+    <value>name</value>
+    <literal>threads</literal>=<value>number</value>
+    [<literal>max_queue</literal>=<value>number</value>]</syntax>
+<default>default threads=32 max_queue=65536</default>
+<context>main</context>
+<appeared-in>1.7.11</appeared-in>
+
+<para>
+Defines named thread pools
+used for multi-threaded reading and sending of files
+<link doc="http/ngx_http_core_module.xml" id="aio">without blocking</link>
+worker processes.
+</para>
+
+<para>
+The <literal>threads</literal> parameter
+defines the number of threads in the pool.
+</para>
+
+<para>
+In the event that all threads in the pool are busy,
+a new task will wait in the queue.
+The <literal>max_queue</literal> parameter limits the number
+of tasks allowed to be waiting in the queue.
+By default, up to 65536 tasks can wait in the queue.
+When the queue overflows, the task is completed with an error.
+</para>
+
+</directive>
+
+
 <directive name="timer_resolution">
 <syntax><value>interval</value></syntax>
 <default/>
--- a/xml/ru/docs/http/ngx_http_core_module.xml	Wed Mar 18 14:19:44 2015 +0000
+++ b/xml/ru/docs/http/ngx_http_core_module.xml	Wed Mar 18 19:01:42 2015 +0300
@@ -17,7 +17,8 @@
 <directive name="aio">
 <syntax>
     <literal>on</literal> |
-    <literal>off</literal></syntax>
+    <literal>off</literal> |
+    <literal>threads</literal>[<literal>=</literal><value>pool</value>]</syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
@@ -118,6 +119,35 @@
 </para>
 
 <para>
+Кроме того, читать и <link id="sendfile">отправлять</link>
+файлы можно в многопоточном режиме (1.7.11),
+не блокируя при этом рабочий процесс:
+<example>
+location /video/ {
+    sendfile       on;
+    aio            threads;
+}
+</example>
+Операции чтения или отправки файлов будут обрабатываться потоками из указанного
+<link doc="../ngx_core_module.xml" id="thread_pool">пула</link>.
+Если пул потоков не задан явно,
+используется пул с именем “<literal>default</literal>”.
+Имя пула может быть задано при помощи переменных:
+<example>
+aio threads=pool$disk;
+</example>
+По умолчанию поддержка многопоточности выключена, её сборку следует
+разрешить с помощью конфигурационного параметра
+<literal>--with-threads</literal>.
+В настоящий момент многопоточность совместима только с методами
+<link doc="../events.xml" id="epoll"/>,
+<link doc="../events.xml" id="kqueue"/>

+<link doc="../events.xml" id="eventport"/>.
+Отправка файлов в многопоточном режиме поддерживается только на Linux.
+</para>
+
+<para>
 См. также директиву <link id="sendfile"/>.
 </para>
 
--- a/xml/ru/docs/ngx_core_module.xml	Wed Mar 18 14:19:44 2015 +0000
+++ b/xml/ru/docs/ngx_core_module.xml	Wed Mar 18 19:01:42 2015 +0300
@@ -395,6 +395,39 @@
 </directive>
 
 
+<directive name="thread_pool">
+<syntax>
+    <value>имя</value>
+    <literal>threads</literal>=<value>число</value>
+    [<literal>max_queue</literal>=<value>число</value>]</syntax>
+<default>default threads=32 max_queue=65536</default>
+<context>main</context>
+<appeared-in>1.7.11</appeared-in>
+
+<para>
+Задаёт именованные пулы потоков,
+используемые для многопоточной обработки операций чтения и отправки файлов
+<link doc="http/ngx_http_core_module.xml" id="aio">без блокирования</link>
+рабочего процесса.
+</para>
+
+<para>
+Параметр <literal>threads</literal>
+задаёт число потоков в пуле.
+</para>
+
+<para>
+Если все потоки из пула заняты выполнением заданий,
+новое задание будет ожидать своего выполнения в очереди.
+Параметр <literal>max_queue</literal> ограничивает число заданий,
+ожидающих своего выполнения в очереди.
+По умолчанию в очереди может находиться до 65536 заданий.
+При переполнении очереди задание завершается с ошибкой.
+</para>
+
+</directive>
+
+
 <directive name="timer_resolution">
 <syntax><value>интервал</value></syntax>
 <default/>