Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_perl_module.xml @ 76:4a4caa566120

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Russian documentation import. Changes in module.dtd: <example> now allowed to contain <value> and <emphasis> elements (we need this to show important parts in examples), less strict checking of <directive> syntax (we don't want to fully document some directives, notably deprecated ones). Known issues: 1. <syntax> elements are preserved as is, they will require manual conversion (likely to some not-yet-existed format a la DocBook cmdsynopsis, as currently used one seems to be incomplete); 2. <value> no longer corresponds to replaceable content, and it's use in examples isn't correct; 3. <link doc="document#fragment"> doesn't work with current xslt, either should be supported or changed to <link doc="document" id="fragment">. The following files are intentionally omitted: maillists.xml (support.xml should be used instead), experimental.xml (obsolete), faq.xml (conflicts with existing one, needs discussion). Not yet linked to site.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 11 Oct 2011 12:57:50 +0000
parents
children 0a45870d0160
comparison
equal deleted inserted replaced
75:2bf4cd2787c5 76:4a4caa566120
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Директивы модуля ngx_http_perl_module"
6 link="/ru/docs/http/ngx_http_perl_module.html"
7 lang="ru">
8
9 <section name="" id="summary">
10
11 <para>
12 Модуль ngx_http_perl_module позволяет работать со встроенным в nginx perl'ом:
13 делать обработчики location и переменной и вставлять вызовы perl'а в SSI.
14 По умолчанию модуль не собирается, нужно разрешить его сборку
15 при конфигурировании параметром <command>--with-http_perl_module</command>.
16 Для сборки необходим perl версии 5.6.1 и выше, и компилятор C, совместимый
17 с тем, которым был собран perl.
18 </para>
19
20 </section>
21
22
23 <section name="Известные проблемы" id="bugs">
24
25 <para>
26 Модуль экспериментальный, поэтому возможно всё.
27 </para>
28
29 <para>
30 Для того, чтобы во время переконфигурации perl перекомпилировал
31 изменённые модули, его нужно собрать с параметрами -Dusemultiplicity=yes
32 или -Dusethreads=yes.
33 Кроме того, чтобы во время работы perl меньше терял память, его нужно собрать
34 с параметром -Dusemymalloc=no.
35 Узнать значения этих параметров у уже собранного
36 perl'а можно так (в примерах приведены желаемые значения параметров):
37 <example>
38 $perl -V:usemultiplicity
39 usemultiplicity='define';
40
41 $perl -V:usemymalloc
42 usemymalloc='n';
43 </example>
44 </para>
45
46 <para>
47 Необходимо учитывать, что после пересборки perl'а с новыми параметрами
48 -Dusemultiplicity=yes или -Dusethreads=yes
49 придётся также переустановить и все бинарные perl'овые модули — они
50 просто перестанут работать с новым perl'ом.
51 </para>
52
53 <para>
54 Возможно, основной процесс, а вслед за ним и рабочие процессы,
55 будет увеличиваться в размерах при каждой переконфигурации.
56 Когда основной процесс вырастет до неприемлемых размеров, можно
57 воспользоваться процедурой
58 <link doc="../control.html#upgrade">обновления сервера на лету</link>,
59 не меняя при этом сам исполняемый файл.
60 </para>
61
62 <para>
63 Если perl'овый модуль выполняет длительную операцию, например, определяет
64 адрес по имени, соединяется с другим сервером, делает запрос к базе данных,
65 то на это время все остальные запросы данного рабочего процесса не будут
66 обрабатываться. Поэтому рекомендуется ограничиться операциями,
67 время исполнения которых короткое и предсказуемое, например, обращение
68 к локальной файловой системе.
69 </para>
70
71 <para>
72 <note>
73
74 <para>
75 Нижеописанные проблемы отностятся только к версиям nignx'а до 0.6.22.
76 </para>
77
78 <para>
79 Данные, возвращаемые методами объекта запроса $r,
80 имеют только текстовое значение, причём само значение хранится
81 в памяти, выделяемой не perl'ом, а nginx'ом из собственных пулов.
82 Это позволяет уменьшить число операций копирования в большинстве случаев,
83 однако в некоторых ситуациях это приводит к ошибке,
84 например, при попытке использования таких значений в численном контексте
85 рабочий процесс выходит с ошибкой (FreeBSD):
86 <example>
87 nginx in realloc(): warning: pointer to wrong page
88 Out of memory!
89 Callback called exit.
90 </example>
91 или (Linux):
92 <example>
93 *** glibc detected *** realloc(): invalid pointer: ... ***
94 Out of memory!
95 Callback called exit.
96 </example>
97 Обход такой ситуации простой — нужно присвоить значение метода
98 переменной, например, такой код
99 <example>
100 my $i = $r-&gt;variable('counter') + 1;
101 </example>
102 нужно заменить на
103 <example>
104 my $i = $r-&gt;variable('counter');
105 $i++;
106 </example>
107 </para>
108
109 <para>
110 Так как строки внутри nginx'а в большинстве случаев хранятся без
111 завершающего нуля, то они в таком же виде возвращаются методами
112 объекта запроса $r (исключения составляют методы $r-&gt;filename
113 и $r-&gt;request_body_file). Поэтому такие значения нельзя использовать
114 в качестве имени файла и тому подобном.
115 Обход такой же, как и предыдущей ситуации — присвоение значения
116 переменной (при этом происходит копирование данных и добавление необходимого
117 нуля) или же использование в выражении, например:
118 <example>
119 open FILE, '/path/' . $r-&gt;variable('name');
120 </example>
121
122 </para>
123
124 </note>
125 </para>
126
127 </section>
128
129
130 <section name="Пример конфигурации" id="example">
131
132 <para>
133 <example>
134 http {
135
136 perl_modules perl/lib;
137 perl_require hello.pm;
138
139 perl_set $msie6 '
140
141 sub {
142 my $r = shift;
143 my $ua = $r-&gt;header_in("User-Agent");
144
145 return "" if $ua =~ /Opera/;
146 return "1" if $ua =~ / MSIE [6-9]\.\d+/;
147 return "";
148 }
149
150 ';
151
152 server {
153 location / {
154 perl hello::handler;
155 }
156 }
157 </example>
158 </para>
159
160 <para>
161 модуль perl/lib/hello.pm:
162 <example>
163 package hello;
164
165 use nginx;
166
167 sub handler {
168 my $r = shift;
169
170 $r-&gt;send_http_header("text/html");
171 return OK if $r-&gt;header_only;
172
173 $r-&gt;print("hello!\n&lt;br/&gt;");
174
175 if (-f $r-&gt;filename or -d _) {
176 $r-&gt;print($r-&gt;uri, " exists!\n");
177 }
178
179 return OK;
180 }
181
182 1;
183 __END__
184
185 </example>
186 </para>
187
188 </section>
189
190
191 <section name="Директивы" id="directives">
192
193 <directive name="perl">
194 <syntax>perl <value>модуль::функция|'sub { ... }'</value></syntax>
195 <default>нет</default>
196 <context>location, limit_except</context>
197
198 <para>
199 Директива устанавливает обработчик для данного location.
200 </para>
201
202 </directive>
203
204
205 <directive name="perl_modules">
206 <syntax>perl_modules <value>путь</value></syntax>
207 <default>нет</default>
208 <context>http</context>
209
210 <para>
211 Директива задаёт дополнительный путь для perl'овых модулей.
212 </para>
213
214 </directive>
215
216
217 <directive name="perl_require">
218 <syntax>perl_require <value>модуль</value></syntax>
219 <default>нет</default>
220 <context>http</context>
221
222 <para>
223 Директива задаёт имя модуля, который будет подгружаться при каждой
224 переконфигурации. Директив может быть несколько.
225 </para>
226
227 </directive>
228
229
230 <directive name="perl_set">
231 <syntax>perl_set <value>$переменная</value>
232 <value>модуль::функция|'sub { ... }'</value>
233 </syntax>
234 <default>нет</default>
235 <context>http</context>
236
237 <para>
238 Директива устанавливает обработчик переменной.
239 </para>
240
241 </directive>
242
243 </section>
244
245
246 <section name="Вызов perl'а из SSI" id="ssi">
247
248 <para>
249 Формат команды следующий:
250 <example>
251 &lt;!--# perl sub="модуль::функция" arg="параметр1" arg="параметр2" ...
252 --&gt;
253 </example>
254 </para>
255
256 </section>
257
258
259 <section name="Методы объекта запроса $r" id="methods">
260
261 <para>
262 <list type="bullet">
263
264 <listitem>
265 <emphasis>$r-&gt;args</emphasis> — метод возвращает аргументы запроса.
266 </listitem>
267
268 <listitem>
269 <emphasis>$r-&gt;filename</emphasis> — метод возвращает имя файла,
270 соответствующее URI запроса.
271 </listitem>
272
273 <listitem>
274 <emphasis>$r-&gt;has_request_body(обработчик)</emphasis> — метод возвращает 0,
275 если в запросе нет тела. Если же тело запроса есть, то устанавливается
276 указанный обработчик и возвращается 1.
277 По окончании приёма тела nginx вызовет установленный обработчик.
278 Обратите внимание, что нужно передавать ссылку на функцию обработчика.
279 Пример использования:
280 <example>
281 package hello;
282
283 use nginx;
284
285 sub handler {
286 my $r = shift;
287
288 if ($r-&gt;request_method ne "POST") {
289 return DECLINED;
290 }
291
292 if ($r-&gt;has_request_body(<emphasis>\&amp;post</emphasis>)) {
293 return OK;
294 }
295
296 return HTTP_BAD_REQUEST;
297 }
298
299 sub <emphasis>post</emphasis> {
300 my $r = shift;
301
302 $r-&gt;send_http_header;
303
304 $r-&gt;print("request_body: \"", $r-&gt;request_body, "\"&lt;br/&gt;");
305 $r-&gt;print("request_body_file: \"", $r-&gt;request_body_file, "\"&lt;br/&gt;\n");
306
307 return OK;
308 }
309
310 1;
311
312 __END__
313 </example>
314 </listitem>
315
316 <listitem>
317 <emphasis>$r-&gt;allow_ranges</emphasis> — метод разрешает использовать
318 byte ranges при передаче ответа.
319 </listitem>
320
321 <listitem>
322 <emphasis>$r-&gt;discard_request_body</emphasis> — метод указывает nginx'у
323 игнорировать тело запроса.
324 </listitem>
325
326 <listitem>
327 <emphasis>$r-&gt;header_in(строка)</emphasis> — метод возвращает значение
328 заданной строки в заголовке запроса клиента.
329 </listitem>
330
331 <listitem>
332 <emphasis>$r-&gt;header_only</emphasis> — метод определяет, нужно ли передавать
333 клиенту только заголовок ответа или весь ответ.
334 </listitem>
335
336 <listitem>
337 <emphasis>$r-&gt;header_out(строка, значение)</emphasis> — метод устанавливает
338 значение для заданной строки в заголовке ответа.
339 </listitem>
340
341 <listitem>
342 <emphasis>$r-&gt;internal_redirect(uri)</emphasis> — метод делает внутренний
343 редирект на указанный uri.
344 Редирект происходит уже после завершения perl'ового обработчика.
345 </listitem>
346
347 <listitem>
348 <emphasis>$r-&gt;print(текст, ...)</emphasis> — метод передаёт клиенту данные.
349 </listitem>
350
351 <listitem>
352 <emphasis>$r-&gt;request_body</emphasis> — метод возвращает тело запроса
353 клиента при условии, что тело не записано во временный файл.
354 Для того, чтобы тело запроса клиента гарантировано находилось в памяти,
355 нужно ограничить его размер с помощью <link doc="ngx_http_core_module.xml#client_max_body_size">client_max_body_size</link>
356 и задать достаточной размер для буфера
357 <link doc="ngx_http_core_module.xml#client_body_buffer_size">client_body_buffer_size</link>.
358 </listitem>
359
360 <listitem>
361 <emphasis>$r-&gt;request_body_file</emphasis> — метод возвращает имя файла,
362 в котором хранится тело запроса клиента.
363 По завершению работы файл необходимо удалить.
364 Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно
365 указать <link doc="ngx_http_core_module.xml#client_body_in_file_only">client_body_in_file_only on</link>.
366 </listitem>
367
368 <listitem>
369 <emphasis>$r-&gt;request_method</emphasis> — метод возвращает HTTP метод
370 запроса клиента.
371 </listitem>
372
373 <listitem>
374 <emphasis>$r-&gt;remote_addr</emphasis> — метод возвращает IP-адрес клиента.
375 </listitem>
376
377 <listitem>
378 <emphasis>$r-&gt;flush</emphasis> — метод немедленно передаёт данные клиенту.
379 </listitem>
380
381 <listitem>
382 <emphasis>$r-&gt;sendfile(имя [, смещение [, длина]])</emphasis> — метод
383 передаёт клиенту содержимое указанного файла. Необязательные параметры
384 указывают начальное смещение и длину передаваемых данных.
385 Собственно передача данных происходит уже после завершения
386 perl'ового обработчика.
387 Необходимо учитывать, что при использовании
388 этого метода в подзапросе и директиве <link doc="ngx_http_core_module.xml#sendfile">sendfile on</link>
389 содержимое файла не будет проходить через
390 <link doc="ngx_http_gzip_module.xml">gzip</link>,
391 <link doc="ngx_http_ssi_module.xml">SSI</link> и
392 <link doc="ngx_http_charset_module.xml">charset</link>
393 фильтры.
394 </listitem>
395
396 <listitem>
397 <emphasis>$r-&gt;send_http_header(<value>тип</value>)</emphasis> — метод
398 передаёт клиенту заголовок ответа.
399 Необязательный параметр "тип" устанавливает значение строки "Content-Type"
400 в заголовке ответа.
401 Пустая строка в качестве типа запрещает строку "Content-Type".
402 </listitem>
403
404 <listitem>
405 <emphasis>$r-&gt;status(код)</emphasis> — метод устанавливает код ответа.
406 </listitem>
407
408 <listitem>
409 <emphasis>$r-&gt;sleep(миллисекунды, обработчик)</emphasis> — метод устанавливает
410 указанный обработчик и останавливает обработку запроса на заданное время.
411 nginx в это время продолжает обрабатывать другие запросы.
412 По истечении указанного времени nginx вызовет установленный обработчик.
413 Обратите внимание, что нужно передавать ссылку на функцию обработчика.
414 Для передачи данных между обработчиками следует использовать $r-&gt;variable().
415 Пример использования:
416 <example>
417 package hello;
418
419 use nginx;
420
421 sub handler {
422 my $r = shift;
423
424 $r-&gt;discard_request_body;
425 $r-&gt;variable("var", "OK");
426 $r-&gt;sleep(1000, <emphasis>\&amp;next</emphasis>);
427
428 return OK;
429 }
430
431 sub <emphasis>next</emphasis> {
432 my $r = shift;
433
434 $r-&gt;send_http_header;
435 $r-&gt;print($r-&gt;variable("var"));
436
437 return OK;
438 }
439
440 1;
441
442 __END__
443 </example>
444 </listitem>
445
446 <listitem>
447 <emphasis>$r-&gt;unescape(текст)</emphasis> — метод декодирует текст,
448 заданный в виде %XX.
449 </listitem>
450
451 <listitem>
452 <emphasis>$r-&gt;uri</emphasis> — метод возвращает URI запроса.
453 </listitem>
454
455 <listitem>
456 <emphasis>$r-&gt;variable(имя [, значение])</emphasis> — метод возвращает
457 или устанавливает значение указанной переменной.
458 Переменные локальны для каждого запроса.
459 </listitem>
460
461 </list>
462 </para>
463
464 </section>
465
466 </module>