Mercurial > hg > nginx-site
changeset 415:c640e00858ed
Revision.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 15 Feb 2012 14:44:37 +0000 |
parents | 71d99de7ff97 |
children | c9c0550465c9 |
files | xml/ru/docs/http/ngx_http_perl_module.xml |
diffstat | 1 files changed, 218 insertions(+), 183 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/ru/docs/http/ngx_http_perl_module.xml Wed Feb 15 14:44:02 2012 +0000 +++ b/xml/ru/docs/http/ngx_http_perl_module.xml Wed Feb 15 14:44:37 2012 +0000 @@ -2,83 +2,86 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Директивы модуля ngx_http_perl_module" +<module name="Модуль ngx_http_perl_module" link="/ru/docs/http/ngx_http_perl_module.html" lang="ru"> <section id="summary"> <para> -Модуль ngx_http_perl_module позволяет работать со встроенным в nginx perl'ом: -делать обработчики location и переменной и вставлять вызовы perl'а в SSI. -По умолчанию модуль не собирается, нужно разрешить его сборку -при конфигурировании параметром <literal>--with-http_perl_module</literal>. -Для сборки необходим perl версии 5.6.1 и выше, и компилятор C, совместимый -с тем, которым был собран perl. +Модуль <literal>ngx_http_perl_module</literal> позволяет писать обработчики +location и переменных на Perl, а также вставлять вызовы Perl в SSI. +</para> + +<para> +По умолчанию этот модуль не собирается, его сборку необходимо +разрешить с помощью конфигурационного параметра +<literal>--with-http_perl_module</literal>. +<note> +Для сборки этого модуля необходим Perl версии 5.6.1 и выше. +Компилятор C должен быть совместим с тем, которым был собран Perl. +</note> </para> </section> -<section name="Известные проблемы" id="bugs"> +<section id="bugs" name="Известные проблемы"> <para> Модуль экспериментальный, поэтому возможно всё. </para> <para> -Для того, чтобы во время переконфигурации perl перекомпилировал -изменённые модули, его нужно собрать с параметрами -Dusemultiplicity=yes -или -Dusethreads=yes. -Кроме того, чтобы во время работы perl меньше терял память, его нужно собрать -с параметром -Dusemymalloc=no. +Для того, чтобы во время переконфигурации Perl перекомпилировал +изменённые модули, его нужно собрать с параметрами +<literal>-Dusemultiplicity=yes</literal> или +<literal>-Dusethreads=yes</literal>. +Кроме того, чтобы во время работы Perl меньше терял память, +его нужно собрать с параметром +<literal>-Dusemymalloc=no</literal>. Узнать значения этих параметров у уже собранного -perl'а можно так (в примерах приведены желаемые значения параметров): +Perl можно так (в примере приведены желаемые значения параметров): <example> -$perl -V:usemultiplicity +$ perl -V:usemultiplicity -V:usemymalloc usemultiplicity='define'; - -$perl -V:usemymalloc usemymalloc='n'; </example> </para> <para> -Необходимо учитывать, что после пересборки perl'а с новыми параметрами --Dusemultiplicity=yes или -Dusethreads=yes -придётся также переустановить и все бинарные perl'овые модули — они -просто перестанут работать с новым perl'ом. +Необходимо учитывать, что после пересборки Perl с новыми параметрами +<literal>-Dusemultiplicity=yes</literal> или +<literal>-Dusethreads=yes</literal> +придётся также пересобрать и все бинарные модули Perl — они +просто перестанут работать с новым Perl. </para> <para> Возможно, основной процесс, а вслед за ним и рабочие процессы, -будет увеличиваться в размерах при каждой переконфигурации. +будут увеличиваться в размерах при каждой переконфигурации. Когда основной процесс вырастет до неприемлемых размеров, можно воспользоваться процедурой -<link doc="../control.html" id="upgrade">обновления сервера на лету</link>, +<link doc="../control.xml" id="upgrade">обновления сервера на лету</link>, не меняя при этом сам исполняемый файл. </para> <para> -Если perl'овый модуль выполняет длительную операцию, например, определяет +Если модуль Perl выполняет длительную операцию, например, определяет адрес по имени, соединяется с другим сервером, делает запрос к базе данных, -то на это время все остальные запросы данного рабочего процесса не будут -обрабатываться. Поэтому рекомендуется ограничиться операциями, +то на это время все остальные запросы, обслуживаемые данным рабочим процессом, +не будут обрабатываться. Поэтому рекомендуется ограничиться операциями, время исполнения которых короткое и предсказуемое, например, обращение к локальной файловой системе. </para> <para> -<note> +Нижеописанные проблемы относятся только к версиям nginx до 0.6.22. -<para> -Нижеописанные проблемы относятся только к версиям nignx'а до 0.6.22. -</para> - -<para> -Данные, возвращаемые методами объекта запроса $r, +<note> +Данные, возвращаемые методами объекта запроса <literal>$r</literal>, имеют только текстовое значение, причём само значение хранится -в памяти, выделяемой не perl'ом, а nginx'ом из собственных пулов. +в памяти, выделяемой не Perl, а nginx из собственных пулов. Это позволяет уменьшить число операций копирования в большинстве случаев, однако в некоторых ситуациях это приводит к ошибке, например, при попытке использования таких значений в численном контексте @@ -97,50 +100,49 @@ Обход такой ситуации простой — нужно присвоить значение метода переменной, например, такой код <example> -my $i = $r->variable('counter') + 1; +my $i = $r->variable('counter') + 1; </example> нужно заменить на <example> -my $i = $r->variable('counter'); +my $i = $r->variable('counter'); $i++; </example> -</para> +</note> -<para> -Так как строки внутри nginx'а в большинстве случаев хранятся без +<note> +Так как строки внутри nginx в большинстве случаев хранятся без завершающего нуля, то они в таком же виде возвращаются методами -объекта запроса $r (исключения составляют методы $r->filename -и $r->request_body_file). Поэтому такие значения нельзя использовать +объекта запроса <literal>$r</literal> (исключения составляют методы +<literal>$r->filename</literal> и <literal>$r->request_body_file</literal>). +Поэтому такие значения нельзя использовать в качестве имени файла и тому подобном. Обход такой же, как и предыдущей ситуации — присвоение значения переменной (при этом происходит копирование данных и добавление необходимого нуля) или же использование в выражении, например: <example> -open FILE, '/path/' . $r->variable('name'); +open FILE, '/path/' . $r->variable('name'); </example> +</note> </para> -</note> -</para> - </section> -<section name="Пример конфигурации" id="example"> +<section id="example" name="Пример конфигурации"> <para> <example> http { - perl_modules perl/lib; - perl_require hello.pm; + perl_modules perl/lib; + perl_require hello.pm; - perl_set $msie6 ' + perl_set $msie6 ' sub { my $r = shift; - my $ua = $r->header_in("User-Agent"); + my $ua = $r->header_in("User-Agent"); return "" if $ua =~ /Opera/; return "1" if $ua =~ / MSIE [6-9]\.\d+/; @@ -151,14 +153,14 @@ server { location / { - perl hello::handler; + perl hello::handler; } } </example> </para> <para> -модуль perl/lib/hello.pm: +Модуль <path>perl/lib/hello.pm</path>: <example> package hello; @@ -167,13 +169,13 @@ sub handler { my $r = shift; - $r->send_http_header("text/html"); - return OK if $r->header_only; + $r->send_http_header("text/html"); + return OK if $r->header_only; - $r->print("hello!\n<br/>"); + $r->print("hello!\n<br/>"); - if (-f $r->filename or -d _) { - $r->print($r->uri, " exists!\n"); + if (-f $r->filename or -d _) { + $r->print($r->uri, " exists!\n"); } return OK; @@ -181,22 +183,22 @@ 1; __END__ - </example> </para> </section> -<section name="Директивы" id="directives"> +<section id="directives" name="Директивы"> <directive name="perl"> -<syntax><value>модуль::функция|'sub { ... }'</value></syntax> +<syntax><value>модуль</value>::<value>функция</value>|'sub { ... }'</syntax> <default/> -<context>location, limit_except</context> +<context>location</context> +<context>limit_except</context> <para> -Директива устанавливает обработчик для данного location. +Устанавливает обработчик Perl для данного location. </para> </directive> @@ -208,7 +210,7 @@ <context>http</context> <para> -Директива задаёт дополнительный путь для perl'овых модулей. +Задаёт дополнительный путь для модулей Perl. </para> </directive> @@ -220,22 +222,23 @@ <context>http</context> <para> -Директива задаёт имя модуля, который будет подгружаться при каждой -переконфигурации. Директив может быть несколько. +Задаёт имя модуля, который будет подгружаться при каждой +переконфигурации. +Директив <literal>perl_require</literal> может быть несколько. </para> </directive> <directive name="perl_set"> -<syntax><value>$переменная</value> - <value>модуль::функция|'sub { ... }'</value> -</syntax> +<syntax> + <value>$переменная</value> + <value>модуль</value>::<value>функция</value>|'sub { ... }'</syntax> <default/> <context>http</context> <para> -Директива устанавливает обработчик переменной. +Устанавливает обработчик Perl для указанной переменной. </para> </directive> @@ -243,12 +246,12 @@ </section> -<section name="Вызов perl'а из SSI" id="ssi"> +<section id="ssi" name="Вызов Perl из SSI"> <para> -Формат команды следующий: +Формат команды SSI с вызовом Perl следующий: <example> -<!--# perl sub="модуль::функция" arg="параметр1" arg="параметр2" ... +<!--# perl sub="<value>модуль</value>::<value>функция</value>" arg="<value>параметр1</value>" arg="<value>параметр2</value>" ... --> </example> </para> @@ -256,27 +259,31 @@ </section> -<section name="Методы объекта запроса $r" id="methods"> +<section id="methods" name="Методы объекта запроса $r"> <para> -<list type="bullet"> +<list type="tag"> -<listitem> -<emphasis>$r->args</emphasis> — метод возвращает аргументы запроса. -</listitem> +<tag-name><literal>$r->args</literal></tag-name> +<tag-desc> +возвращает аргументы запроса. +</tag-desc> -<listitem> -<emphasis>$r->filename</emphasis> — метод возвращает имя файла, -соответствующее URI запроса. -</listitem> +<tag-name><literal>$r->filename</literal></tag-name> +<tag-desc> +возвращает имя файла, соответствующее URI запроса. +</tag-desc> -<listitem> -<emphasis>$r->has_request_body(обработчик)</emphasis> — метод возвращает 0, -если в запросе нет тела. Если же тело запроса есть, то устанавливается +<tag-name> + <literal>$r->has_request_body(<value>обработчик</value>)</literal> +</tag-name> +<tag-desc> +возвращает 0, если в запросе нет тела. +Если же тело запроса есть, то устанавливается указанный обработчик и возвращается 1. -По окончании приёма тела nginx вызовет установленный обработчик. +По окончании чтения тела запроса nginx вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. -Пример использования: +Пример: <example> package hello; @@ -285,11 +292,11 @@ sub handler { my $r = shift; - if ($r->request_method ne "POST") { + if ($r->request_method ne "POST") { return DECLINED; } - if ($r->has_request_body(<emphasis>\&post</emphasis>)) { + if ($r->has_request_body(<emphasis>\&post</emphasis>)) { return OK; } @@ -299,10 +306,10 @@ sub <emphasis>post</emphasis> { my $r = shift; - $r->send_http_header; + $r->send_http_header; - $r->print("request_body: \"", $r->request_body, "\"<br/>"); - $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); + $r->print("request_body: \"", $r->request_body, "\"<br/>"); + $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); return OK; } @@ -311,110 +318,134 @@ __END__ </example> -</listitem> +</tag-desc> -<listitem> -<emphasis>$r->allow_ranges</emphasis> — метод разрешает использовать -byte ranges при передаче ответа. -</listitem> +<tag-name><literal>$r->allow_ranges</literal></tag-name> +<tag-desc> +разрешает использовать диапазоны байт (byte ranges) при передаче ответа. +</tag-desc> -<listitem> -<emphasis>$r->discard_request_body</emphasis> — метод указывает nginx'у -игнорировать тело запроса. -</listitem> +<tag-name><literal>$r->discard_request_body</literal></tag-name> +<tag-desc> +указывает nginx игнорировать тело запроса. +</tag-desc> -<listitem> -<emphasis>$r->header_in(строка)</emphasis> — метод возвращает значение -заданной строки в заголовке запроса клиента. -</listitem> +<tag-name><literal>$r->header_in(<value>поле</value>)</literal></tag-name> +<tag-desc> +возвращает значение заданного поля в заголовке запроса клиента. +</tag-desc> + +<tag-name><literal>$r->header_only</literal></tag-name> +<tag-desc> +определяет, нужно ли передавать клиенту только заголовок ответа или весь ответ. +</tag-desc> -<listitem> -<emphasis>$r->header_only</emphasis> — метод определяет, нужно ли передавать -клиенту только заголовок ответа или весь ответ. -</listitem> - -<listitem> -<emphasis>$r->header_out(строка, значение)</emphasis> — метод устанавливает -значение для заданной строки в заголовке ответа. -</listitem> +<tag-name> + <literal>$r->header_out(<value>поле</value>, + <value>значение</value>)</literal> +</tag-name> +<tag-desc> +устанавливает значение для заданного поля в заголовке ответа. +</tag-desc> -<listitem> -<emphasis>$r->internal_redirect(uri)</emphasis> — метод делает внутреннее -перенаправление на указанный uri. -Перенаправление происходит уже после завершения perl'ового обработчика. -</listitem> +<tag-name> + <literal>$r->internal_redirect(<value>uri</value>)</literal> +</tag-name> +<tag-desc> +делает внутреннее перенаправление на указанный <value>uri</value>. +Перенаправление происходит уже после завершения обработчика Perl. +</tag-desc> -<listitem> -<emphasis>$r->print(текст, ...)</emphasis> — метод передаёт клиенту данные. -</listitem> +<tag-name><literal>$r->print(<value>текст</value>, ...)</literal></tag-name> +<tag-desc> +метод передаёт клиенту данные. +</tag-desc> -<listitem> -<emphasis>$r->request_body</emphasis> — метод возвращает тело запроса -клиента при условии, что тело не записано во временный файл. -Для того, чтобы тело запроса клиента гарантировано находилось в памяти, +<tag-name><literal>$r->request_body</literal></tag-name> +<tag-desc> +возвращает тело запроса клиента при условии, +что тело не записано во временный файл. +Для того, чтобы тело запроса клиента гарантированно находилось в памяти, нужно ограничить его размер с помощью <link doc="ngx_http_core_module.xml" id="client_max_body_size"/> и задать достаточной размер для буфера <link doc="ngx_http_core_module.xml" id="client_body_buffer_size"/>. -</listitem> +</tag-desc> -<listitem> -<emphasis>$r->request_body_file</emphasis> — метод возвращает имя файла, -в котором хранится тело запроса клиента. -По завершению работы файл необходимо удалить. -Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно -указать <link doc="ngx_http_core_module.xml" id="client_body_in_file_only">client_body_in_file_only on</link>. -</listitem> +<tag-name><literal>$r->request_body_file</literal></tag-name> +<tag-desc> +возвращает имя файла, в котором хранится тело запроса клиента. +По завершению обработки файл необходимо удалить. +Для того, чтобы тело запроса клиента всегда записывалось в файл, +следует включить +<link doc="ngx_http_core_module.xml" id="client_body_in_file_only"/>. +</tag-desc> -<listitem> -<emphasis>$r->request_method</emphasis> — метод возвращает HTTP метод -запроса клиента. -</listitem> +<tag-name><literal>$r->request_method</literal></tag-name> +<tag-desc> +возвращает HTTP-метод запроса клиента. +</tag-desc> -<listitem> -<emphasis>$r->remote_addr</emphasis> — метод возвращает IP-адрес клиента. -</listitem> +<tag-name><literal>$r->remote_addr</literal></tag-name> +<tag-desc> +возвращает IP-адрес клиента. +</tag-desc> -<listitem> -<emphasis>$r->flush</emphasis> — метод немедленно передаёт данные клиенту. -</listitem> +<tag-name><literal>$r->flush</literal></tag-name> +<tag-desc> +немедленно передаёт данные клиенту. +</tag-desc> -<listitem> -<emphasis>$r->sendfile(имя [, смещение [, длина]])</emphasis> — метод -передаёт клиенту содержимое указанного файла. Необязательные параметры -указывают начальное смещение и длину передаваемых данных. -Собственно передача данных происходит уже после завершения -perl'ового обработчика. +<tag-name> + <literal>$r->sendfile(<value>имя</value>[, + <value>смещение</value>[, + <value>длина</value>]])</literal> +</tag-name> +<tag-desc> +передаёт клиенту содержимое указанного файла. +Необязательные параметры +задают начальное смещение и длину передаваемых данных. +Непосредственно передача данных происходит уже после завершения +обработчика Perl. Необходимо учитывать, что при использовании -этого метода в подзапросе и директиве -<link doc="ngx_http_core_module.xml" id="sendfile">sendfile on</link> +этого метода в подзапросе и включённой директиве +<link doc="ngx_http_core_module.xml" id="sendfile"/> содержимое файла не будет проходить через <link doc="ngx_http_gzip_module.xml">gzip</link>, <link doc="ngx_http_ssi_module.xml">SSI</link> и <link doc="ngx_http_charset_module.xml">charset</link> фильтры. -</listitem> +</tag-desc> -<listitem> -<emphasis>$r->send_http_header(<value>тип</value>)</emphasis> — метод +<tag-name> + <literal>$r->send_http_header([<value>тип</value>])</literal> +</tag-name> +<tag-desc> передаёт клиенту заголовок ответа. -Необязательный параметр "тип" устанавливает значение строки "Content-Type" -в заголовке ответа. -Пустая строка в качестве типа запрещает строку "Content-Type". -</listitem> +Необязательный параметр <value>тип</value> устанавливает значение поля +<header>Content-Type</header> в заголовке ответа. +Пустая строка в качестве типа запрещает передачу поля +<header>Content-Type</header>. +</tag-desc> -<listitem> -<emphasis>$r->status(код)</emphasis> — метод устанавливает код ответа. -</listitem> +<tag-name><literal>$r->status(<value>код</value>)</literal></tag-name> +<tag-desc> +устанавливает код ответа. +</tag-desc> -<listitem> -<emphasis>$r->sleep(миллисекунды, обработчик)</emphasis> — метод устанавливает -указанный обработчик и останавливает обработку запроса на заданное время. +<tag-name> + <literal>$r->sleep(<value>миллисекунды</value>, + <value>обработчик</value>)</literal> +</tag-name> +<tag-desc> +устанавливает указанный обработчик +и останавливает обработку запроса на заданное время. nginx в это время продолжает обрабатывать другие запросы. По истечении указанного времени nginx вызовет установленный обработчик. Обратите внимание, что нужно передавать ссылку на функцию обработчика. -Для передачи данных между обработчиками следует использовать $r->variable(). -Пример использования: +Для передачи данных между обработчиками следует использовать +<literal>$r->variable()</literal>. +Пример: <example> package hello; @@ -423,9 +454,9 @@ sub handler { my $r = shift; - $r->discard_request_body; - $r->variable("var", "OK"); - $r->sleep(1000, <emphasis>\&next</emphasis>); + $r->discard_request_body; + $r->variable("var", "OK"); + $r->sleep(1000, <emphasis>\&next</emphasis>); return OK; } @@ -433,8 +464,8 @@ sub <emphasis>next</emphasis> { my $r = shift; - $r->send_http_header; - $r->print($r->variable("var")); + $r->send_http_header; + $r->print($r->variable("var")); return OK; } @@ -443,22 +474,26 @@ __END__ </example> -</listitem> +</tag-desc> -<listitem> -<emphasis>$r->unescape(текст)</emphasis> — метод декодирует текст, -заданный в виде %XX. -</listitem> +<tag-name><literal>$r->unescape(<value>текст</value>)</literal></tag-name> +<tag-desc> +декодирует текст, заданный в виде “%XX”. +</tag-desc> -<listitem> -<emphasis>$r->uri</emphasis> — метод возвращает URI запроса. -</listitem> +<tag-name><literal>$r->uri</literal></tag-name> +<tag-desc> +возвращает URI запроса. +</tag-desc> -<listitem> -<emphasis>$r->variable(имя [, значение])</emphasis> — метод возвращает -или устанавливает значение указанной переменной. +<tag-name> + <literal>$r->variable(<value>имя</value>[, + <value>значение</value>])</literal> +</tag-name> +<tag-desc> +возвращает или устанавливает значение указанной переменной. Переменные локальны для каждого запроса. -</listitem> +</tag-desc> </list> </para>