Mercurial > hg > nginx-site
comparison xml/ru/docs/http/ngx_http_perl_module.xml @ 76:4a4caa566120
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->variable('counter') + 1; | |
101 </example> | |
102 нужно заменить на | |
103 <example> | |
104 my $i = $r->variable('counter'); | |
105 $i++; | |
106 </example> | |
107 </para> | |
108 | |
109 <para> | |
110 Так как строки внутри nginx'а в большинстве случаев хранятся без | |
111 завершающего нуля, то они в таком же виде возвращаются методами | |
112 объекта запроса $r (исключения составляют методы $r->filename | |
113 и $r->request_body_file). Поэтому такие значения нельзя использовать | |
114 в качестве имени файла и тому подобном. | |
115 Обход такой же, как и предыдущей ситуации — присвоение значения | |
116 переменной (при этом происходит копирование данных и добавление необходимого | |
117 нуля) или же использование в выражении, например: | |
118 <example> | |
119 open FILE, '/path/' . $r->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->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->send_http_header("text/html"); | |
171 return OK if $r->header_only; | |
172 | |
173 $r->print("hello!\n<br/>"); | |
174 | |
175 if (-f $r->filename or -d _) { | |
176 $r->print($r->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 <!--# perl sub="модуль::функция" arg="параметр1" arg="параметр2" ... | |
252 --> | |
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->args</emphasis> — метод возвращает аргументы запроса. | |
266 </listitem> | |
267 | |
268 <listitem> | |
269 <emphasis>$r->filename</emphasis> — метод возвращает имя файла, | |
270 соответствующее URI запроса. | |
271 </listitem> | |
272 | |
273 <listitem> | |
274 <emphasis>$r->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->request_method ne "POST") { | |
289 return DECLINED; | |
290 } | |
291 | |
292 if ($r->has_request_body(<emphasis>\&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->send_http_header; | |
303 | |
304 $r->print("request_body: \"", $r->request_body, "\"<br/>"); | |
305 $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); | |
306 | |
307 return OK; | |
308 } | |
309 | |
310 1; | |
311 | |
312 __END__ | |
313 </example> | |
314 </listitem> | |
315 | |
316 <listitem> | |
317 <emphasis>$r->allow_ranges</emphasis> — метод разрешает использовать | |
318 byte ranges при передаче ответа. | |
319 </listitem> | |
320 | |
321 <listitem> | |
322 <emphasis>$r->discard_request_body</emphasis> — метод указывает nginx'у | |
323 игнорировать тело запроса. | |
324 </listitem> | |
325 | |
326 <listitem> | |
327 <emphasis>$r->header_in(строка)</emphasis> — метод возвращает значение | |
328 заданной строки в заголовке запроса клиента. | |
329 </listitem> | |
330 | |
331 <listitem> | |
332 <emphasis>$r->header_only</emphasis> — метод определяет, нужно ли передавать | |
333 клиенту только заголовок ответа или весь ответ. | |
334 </listitem> | |
335 | |
336 <listitem> | |
337 <emphasis>$r->header_out(строка, значение)</emphasis> — метод устанавливает | |
338 значение для заданной строки в заголовке ответа. | |
339 </listitem> | |
340 | |
341 <listitem> | |
342 <emphasis>$r->internal_redirect(uri)</emphasis> — метод делает внутренний | |
343 редирект на указанный uri. | |
344 Редирект происходит уже после завершения perl'ового обработчика. | |
345 </listitem> | |
346 | |
347 <listitem> | |
348 <emphasis>$r->print(текст, ...)</emphasis> — метод передаёт клиенту данные. | |
349 </listitem> | |
350 | |
351 <listitem> | |
352 <emphasis>$r->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->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->request_method</emphasis> — метод возвращает HTTP метод | |
370 запроса клиента. | |
371 </listitem> | |
372 | |
373 <listitem> | |
374 <emphasis>$r->remote_addr</emphasis> — метод возвращает IP-адрес клиента. | |
375 </listitem> | |
376 | |
377 <listitem> | |
378 <emphasis>$r->flush</emphasis> — метод немедленно передаёт данные клиенту. | |
379 </listitem> | |
380 | |
381 <listitem> | |
382 <emphasis>$r->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->send_http_header(<value>тип</value>)</emphasis> — метод | |
398 передаёт клиенту заголовок ответа. | |
399 Необязательный параметр "тип" устанавливает значение строки "Content-Type" | |
400 в заголовке ответа. | |
401 Пустая строка в качестве типа запрещает строку "Content-Type". | |
402 </listitem> | |
403 | |
404 <listitem> | |
405 <emphasis>$r->status(код)</emphasis> — метод устанавливает код ответа. | |
406 </listitem> | |
407 | |
408 <listitem> | |
409 <emphasis>$r->sleep(миллисекунды, обработчик)</emphasis> — метод устанавливает | |
410 указанный обработчик и останавливает обработку запроса на заданное время. | |
411 nginx в это время продолжает обрабатывать другие запросы. | |
412 По истечении указанного времени nginx вызовет установленный обработчик. | |
413 Обратите внимание, что нужно передавать ссылку на функцию обработчика. | |
414 Для передачи данных между обработчиками следует использовать $r->variable(). | |
415 Пример использования: | |
416 <example> | |
417 package hello; | |
418 | |
419 use nginx; | |
420 | |
421 sub handler { | |
422 my $r = shift; | |
423 | |
424 $r->discard_request_body; | |
425 $r->variable("var", "OK"); | |
426 $r->sleep(1000, <emphasis>\&next</emphasis>); | |
427 | |
428 return OK; | |
429 } | |
430 | |
431 sub <emphasis>next</emphasis> { | |
432 my $r = shift; | |
433 | |
434 $r->send_http_header; | |
435 $r->print($r->variable("var")); | |
436 | |
437 return OK; | |
438 } | |
439 | |
440 1; | |
441 | |
442 __END__ | |
443 </example> | |
444 </listitem> | |
445 | |
446 <listitem> | |
447 <emphasis>$r->unescape(текст)</emphasis> — метод декодирует текст, | |
448 заданный в виде %XX. | |
449 </listitem> | |
450 | |
451 <listitem> | |
452 <emphasis>$r->uri</emphasis> — метод возвращает URI запроса. | |
453 </listitem> | |
454 | |
455 <listitem> | |
456 <emphasis>$r->variable(имя [, значение])</emphasis> — метод возвращает | |
457 или устанавливает значение указанной переменной. | |
458 Переменные локальны для каждого запроса. | |
459 </listitem> | |
460 | |
461 </list> | |
462 </para> | |
463 | |
464 </section> | |
465 | |
466 </module> |