Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1899:b86cfece30c3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added development guide.
author Vladimir Homutov <vl@nginx.com>
date Fri, 10 Feb 2017 16:54:24 +0300
parents
children 862e96a39fe3
comparison
equal deleted inserted replaced
1898:d83f7372feb5 1899:b86cfece30c3
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8
9 <article name="Development guide"
10 link="/en/docs/dev/development_guide.html"
11 lang="en"
12 rev="1">
13
14 <section name="Introduction" id="introduction">
15
16
17 <section name="Code layout" id="code_layout">
18
19 <para>
20 <list type="bullet">
21 <listitem>
22 <literal>auto</literal> - build scripts
23 </listitem>
24
25 <listitem>
26 <literal>src</literal>
27
28 <list type="bullet">
29
30 <listitem>
31 <literal>core</literal> - basic types and functions - string, array, log,
32 pool etc
33 </listitem>
34
35 <listitem>
36 <literal>event</literal> - event core
37
38 <list type="bullet">
39
40 <listitem>
41 <literal>modules</literal> - event notification modules: epoll, kqueue,
42 select etc
43 </listitem>
44
45 </list>
46
47 </listitem>
48
49 <listitem>
50 <literal>http</literal> - core HTTP module and common code
51
52 <list type="bullet">
53
54 <listitem>
55 <literal>modules</literal> - other HTTP modules
56 </listitem>
57
58 <listitem>
59 <literal>v2</literal> - HTTPv2
60 </listitem>
61
62 </list>
63
64 </listitem>
65
66 <listitem>
67 <literal>mail</literal> - mail modules
68 </listitem>
69
70 <listitem>
71 <literal>os</literal> - platform-specific code
72
73 <list type="bullet">
74
75 <listitem>
76 <literal>unix</literal>
77 </listitem>
78
79 <listitem>
80 <literal>win32</literal>
81 </listitem>
82
83 </list>
84
85 </listitem>
86
87 <listitem>
88 <literal>stream</literal> - stream modules
89 </listitem>
90
91 </list>
92
93 </listitem>
94
95 </list>
96 </para>
97
98 </section>
99
100
101 <section name="Include files" id="include_files">
102
103 <para>
104 Each nginx file should start with including the following two files:
105 </para>
106
107
108 <programlisting>
109 #include &lt;ngx_config.h>
110 #include &lt;ngx_core.h>
111 </programlisting>
112
113 <para>
114 In addition to that, HTTP code should include
115 </para>
116
117
118 <programlisting>
119 #include &lt;ngx_http.h>
120 </programlisting>
121
122 <para>
123 Mail code should include
124 </para>
125
126
127 <programlisting>
128 #include &lt;ngx_mail.h>
129 </programlisting>
130
131 <para>
132 Stream code should include
133 </para>
134
135
136 <programlisting>
137 #include &lt;ngx_stream.h>
138 </programlisting>
139
140 </section>
141
142
143 <section name="Integers" id="integers">
144
145 <para>
146 For general purpose, nginx code uses the following two integer types
147 <literal>ngx_int_t</literal> and <literal>ngx_uint_t</literal> which are
148 typedefs for <literal>intptr_t</literal> and <literal>uintptr_t</literal>.
149 </para>
150
151 </section>
152
153
154 <section name="Common return codes" id="common_return_codes">
155
156 <para>
157 Most functions in nginx return the following codes:
158 </para>
159
160 <para>
161 <list type="bullet">
162
163 <listitem>
164 <literal>NGX_OK</literal> - operation succeeded
165 </listitem>
166
167 <listitem>
168 <literal>NGX_ERROR</literal> - operation failed
169 </listitem>
170
171 <listitem>
172 <literal>NGX_AGAIN</literal> - operation incomplete, function should be called
173 again
174 </listitem>
175
176 <listitem>
177 <literal>NGX_DECLINED</literal> - operation rejected, for example, if disabled
178 in configuration. This is never an error
179 </listitem>
180
181 <listitem>
182 <literal>NGX_BUSY</literal> - resource is not available
183 </listitem>
184
185 <listitem>
186 <literal>NGX_DONE</literal> - operation done or continued elsewhere.
187 Also used as an alternative success code
188 </listitem>
189
190 <listitem>
191 <literal>NGX_ABORT</literal> - function was aborted.
192 Also used as an alternative error code
193 </listitem>
194
195 </list>
196 </para>
197
198 </section>
199
200
201 <section name="Error handling" id="error_handling">
202
203 <para>
204 For getting the last system error code, the <literal>ngx_errno</literal> macro
205 is available.
206 It's mapped to <literal>errno</literal> on POSIX platforms and to
207 <literal>GetLastError()</literal> call in Windows.
208 For getting the last socket error number, the
209 <literal>ngx_socket_errno</literal> macro is available.
210 It's mapped to <literal>errno</literal> on POSIX systems as well,
211 and to <literal>WSAGetLastError()</literal> call on Windows.
212 For performance reasons the values of <literal>ngx_errno</literal> or
213 <literal>ngx_socket_errno</literal> should not be accessed more than
214 once in a row.
215 The error value should be stored in a local variable of type
216 <literal>ngx_err_t</literal> for using multiple times, if required.
217 For setting errors, <literal>ngx_set_errno(errno)</literal> and
218 <literal>ngx_set_socket_errno(errno)</literal> macros are available.
219 </para>
220
221 <para>
222 The values of <literal>ngx_errno</literal> or
223 <literal>ngx_socket_errno</literal> can be passed to logging functions
224 <literal>ngx_log_error()</literal> and <literal>ngx_log_debugX()</literal>, in
225 which case system error text is added to the log message.
226 </para>
227
228 <para>
229 Example using <literal>ngx_errno</literal>:
230 </para>
231
232
233 <programlisting>
234 void
235 ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
236 {
237 ngx_err_t err;
238
239 if (kill(pid, signo) == -1) {
240 err = ngx_errno;
241
242 ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);
243
244 if (err == NGX_ESRCH) {
245 return 2;
246 }
247
248 return 1;
249 }
250
251 return 0;
252 }
253 </programlisting>
254
255 </section>
256
257
258 </section>
259
260
261 <section name="Strings" id="strings">
262
263
264 <section name="Overview" id="overview">
265
266 <para>
267 For C strings, nginx code uses unsigned character type pointer
268 <literal>u_char *</literal>.
269 </para>
270
271 <para>
272 The nginx string type <literal>ngx_str_t</literal> is defined as follows:
273 </para>
274
275
276 <programlisting>
277 typedef struct {
278 size_t len;
279 u_char *data;
280 } ngx_str_t;
281 </programlisting>
282
283 <para>
284 The <literal>len</literal> field holds the string length,
285 <literal>data</literal> holds the string data.
286 The string, held in <literal>ngx_str_t</literal>, may or may not be
287 null-terminated after the <literal>len</literal> bytes.
288 In most cases it’s not.
289 However, in certain parts of code (for example, when parsing configuration),
290 <literal>ngx_str_t</literal> objects are known to be null-terminated, and that
291 knowledge is used to simplify string comparison and makes it easier to pass
292 those strings to syscalls.
293 </para>
294
295 <para>
296 A number of string operations are provided in nginx.
297 They are declared in <literal>src/core/ngx_string.h</literal>.
298 Some of them are wrappers around standard C functions:
299 </para>
300
301 <para>
302 <list type="bullet">
303
304 <listitem>
305 <literal>ngx_strcmp()</literal>
306 </listitem>
307
308 <listitem>
309 <literal>ngx_strncmp()</literal>
310 </listitem>
311
312 <listitem>
313 <literal>ngx_strstr()</literal>
314 </listitem>
315
316 <listitem>
317 <literal>ngx_strlen()</literal>
318 </listitem>
319
320 <listitem>
321 <literal>ngx_strchr()</literal>
322 </listitem>
323
324 <listitem>
325 <literal>ngx_memcmp()</literal>
326 </listitem>
327
328 <listitem>
329 <literal>ngx_memset()</literal>
330 </listitem>
331
332 <listitem>
333 <literal>ngx_memcpy()</literal>
334 </listitem>
335
336 <listitem>
337 <literal>ngx_memmove()</literal>
338 </listitem>
339
340 </list>
341
342 </para>
343
344 <para>
345 Some nginx-specific string functions:
346 </para>
347
348 <para>
349 <list type="bullet">
350
351 <listitem>
352 <literal>ngx_memzero()</literal> fills memory with zeroes
353 </listitem>
354
355 <listitem>
356 <literal>ngx_cpymem()</literal> does the same as
357 <literal>ngx_memcpy()</literal>, but returns the final destination address
358 This one is handy for appending multiple strings in a row
359 </listitem>
360
361 <listitem>
362 <literal>ngx_movemem()</literal> does the same as
363 <literal>ngx_memmove()</literal>, but returns the final destination address.
364 </listitem>
365
366 <listitem>
367 <literal>ngx_strlchr()</literal> searches for a character in a string,
368 delimited by two pointers
369 </listitem>
370 </list>
371 </para>
372
373 <para>
374 Some case conversion and comparison functions:
375 </para>
376
377 <para>
378 <list type="bullet">
379
380 <listitem>
381 <literal>ngx_tolower()</literal>
382 </listitem>
383
384 <listitem>
385 <literal>ngx_toupper()</literal>
386 </listitem>
387
388 <listitem>
389 <literal>ngx_strlow()</literal>
390 </listitem>
391
392 <listitem>
393 <literal>ngx_strcasecmp()</literal>
394 </listitem>
395
396 <listitem>
397 <literal>ngx_strncasecmp()</literal>
398 </listitem>
399
400 </list>
401 </para>
402
403 </section>
404
405
406 <section name="Formatting" id="formatting">
407
408 <para>
409 A number of formatting functions are provided by nginx. These functions support nginx-specific types:
410 </para>
411
412
413 <para>
414 <list type="bullet">
415
416 <listitem>
417 <literal>ngx_sprintf(buf, fmt, ...)</literal>
418 </listitem>
419
420 <listitem>
421 <literal>ngx_snprintf(buf, max, fmt, ...)</literal>
422 </listitem>
423
424 <listitem>
425 <literal>ngx_slrintf(buf, last, fmt, ...)</literal>
426 </listitem>
427
428 <listitem>
429 <literal>ngx_vslprint(buf, last, fmt, args)</literal>
430 </listitem>
431
432 <listitem>
433 <literal>ngx_vsnprint(buf, max, fmt, args)</literal>
434 </listitem>
435
436 </list>
437 </para>
438
439 <para>
440 The full list of formatting options, supported by these functions, can be found
441 in <literal>src/core/ngx_string.c</literal>. Some of them are:
442 </para>
443
444
445 <programlisting>
446 %O - off_t
447 %T - time_t
448 %z - size_t
449 %i - ngx_int_t
450 %p - void *
451 %V - ngx_str_t *
452 %s - u_char * (null-terminated)
453 %*s - size_t + u_char *
454 </programlisting>
455
456 <para>
457 The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex.
458 </para>
459
460 <para>
461 Example:
462
463 <programlisting>
464 u_char buf[NGX_INT_T_LEN];
465 size_t len;
466 ngx_int_t n;
467
468 /* set n here */
469
470 len = ngx_sprintf(buf, "%ui", n) - buf;
471 </programlisting>
472
473 </para>
474
475 </section>
476
477
478 <section name="Numeric conversion" id="numeric_conversion">
479
480 <para>
481 Several functions for numeric conversion are implemented in nginx:
482 </para>
483
484 <para>
485 <list type="bullet">
486
487 <listitem>
488 <literal>ngx_atoi(line, n)</literal> - converts a string of given length to a
489 positive integer of type <literal>ngx_int_t</literal>.
490 Returns <literal>NGX_ERROR</literal> on error
491 </listitem>
492
493 <listitem>
494 <literal>ngx_atosz(line, n)</literal> - same for <literal>ssize_t</literal>
495 type
496 </listitem>
497
498 <listitem>
499 <literal>ngx_atoof(line, n)</literal> - same for <literal>off_t</literal>
500 type
501 </listitem>
502
503 <listitem>
504 <literal>ngx_atotm(line, n)</literal> - same for <literal>time_t</literal>
505 type
506 </listitem>
507
508 <listitem>
509 <literal>ngx_atofp(line, n, point)</literal> - converts a fixed point floating
510 number of given length to a positive integer of type
511 <literal>ngx_int_t</literal>.
512 The result is shifted left by <literal>points</literal> decimal
513 positions. The string representation of the number is expected to have no more
514 than <literal>points</literal> fractional digits.
515 Returns <literal>NGX_ERROR</literal> on error. For example,
516 <literal>ngx_atofp("10.5", 4, 2)</literal> returns <literal>1050</literal>
517 </listitem>
518
519 <listitem>
520 <literal>ngx_hextoi(line, n)</literal> - converts hexadecimal representation of
521 a positive integer to <literal>ngx_int_t</literal>. Returns
522 <literal>NGX_ERROR</literal> on error
523 </listitem>
524
525 </list>
526 </para>
527
528 </section>
529
530
531 </section>
532
533
534 <section name="Containers" id="containers">
535
536
537 <section name="Array" id="array">
538
539 <para>
540 The nginx array type <literal>ngx_array_t</literal> is defined as follows
541 </para>
542
543
544 <programlisting>
545 typedef struct {
546 void *elts;
547 ngx_uint_t nelts;
548 size_t size;
549 ngx_uint_t nalloc;
550 ngx_pool_t *pool;
551 } ngx_array_t;
552 </programlisting>
553
554 <para>
555 The elements of array are available through the <literal>elts</literal> field.
556 The number of elements is held in the <literal>nelts</literal> field.
557 The <literal>size</literal> field holds the size of a single element and is set
558 when initializing the array.
559 </para>
560
561 <para>
562 An array can be created in a pool with the
563 <literal>ngx_array_create(pool, n, size)</literal> call.
564 An already allocated array object can be initialized with the
565 <literal>ngx_array_init(array, pool, n, size)</literal> call.
566 </para>
567
568
569 <programlisting>
570 ngx_array_t *a, b;
571
572 /* create an array of strings with preallocated memory for 10 elements */
573 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
574
575 /* initialize string array for 10 elements */
576 ngx_array_init(&amp;b, pool, 10, sizeof(ngx_str_t));
577 </programlisting>
578
579 <para>
580 Adding elements to array are done with the following functions:
581 </para>
582
583 <para>
584 <list type="bullet">
585
586 <listitem>
587 <literal>ngx_array_push(a)</literal> adds one tail element and returns pointer
588 to it
589 </listitem>
590
591 <listitem>
592 <literal>ngx_array_push_n(a, n)</literal> adds <literal>n</literal> tail elements
593 and returns pointer to the first one
594 </listitem>
595
596 </list>
597 </para>
598
599 <para>
600 If currently allocated memory is not enough for new elements, a new memory for
601 elements is allocated and existing elements are copied to that memory.
602 The new memory block is normally twice as large, as the existing one.
603 </para>
604
605
606 <programlisting>
607 s = ngx_array_push(a);
608 ss = ngx_array_push_n(&amp;b, 3);
609 </programlisting>
610
611 </section>
612
613
614 <section name="List" id="list">
615
616 <para>
617 List in nginx is a sequence of arrays, optimized for inserting a potentially
618 large number of items. The list type is defined as follows:
619 </para>
620
621
622 <programlisting>
623 typedef struct {
624 ngx_list_part_t *last;
625 ngx_list_part_t part;
626 size_t size;
627 ngx_uint_t nalloc;
628 ngx_pool_t *pool;
629 } ngx_list_t;
630 </programlisting>
631
632 <para>
633 The actual items are store in list parts, defined as follows:
634 </para>
635
636
637 <programlisting>
638 typedef struct ngx_list_part_s ngx_list_part_t;
639
640 struct ngx_list_part_s {
641 void *elts;
642 ngx_uint_t nelts;
643 ngx_list_part_t *next;
644 };
645 </programlisting>
646
647 <para>
648 Initially, a list must be initialized by calling
649 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
650 <literal>ngx_list_create(pool, n, size)</literal>.
651 Both functions receive the size of a single item and a number of items per list
652 part.
653 The <literal>ngx_list_push(list)</literal> function is used to add an item to the
654 list. Iterating over the items is done by direct accessing the list fields, as
655 seen in the example:
656 </para>
657
658
659 <programlisting>
660 ngx_str_t *v;
661 ngx_uint_t i;
662 ngx_list_t *list;
663 ngx_list_part_t *part;
664
665 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
666 if (list == NULL) { /* error */ }
667
668 /* add items to the list */
669
670 v = ngx_list_push(list);
671 if (v == NULL) { /* error */ }
672 ngx_str_set(v, “foo”);
673
674 v = ngx_list_push(list);
675 if (v == NULL) { /* error */ }
676 ngx_str_set(v, “bar”);
677
678 /* iterate over the list */
679
680 part = &amp;list->part;
681 v = part->elts;
682
683 for (i = 0; /* void */; i++) {
684
685 if (i >= part->nelts) {
686 if (part->next == NULL) {
687 break;
688 }
689
690 part = part->next;
691 v = part->elts;
692 i = 0;
693 }
694
695 ngx_do_smth(&amp;v[i]);
696 }
697 </programlisting>
698
699 <para>
700 The primary use for the list in nginx is HTTP input and output headers.
701 </para>
702
703 <para>
704 The list does not support item removal.
705 However, when needed, items can internally be marked as missing without actual
706 removing from the list.
707 For example, HTTP output headers which are stored as
708 <literal>ngx_table_elt_t</literal> objects, are marked as missing by setting
709 the <literal>hash</literal> field of <literal>ngx_table_elt_t</literal> to
710 zero. Such items are explicitly skipped, when iterating over the headers.
711 </para>
712
713 </section>
714
715
716 <section name="Queue" id="queue">
717
718 <para>
719 Queue in nginx is an intrusive doubly linked list, with each node defined as
720 follows:
721 </para>
722
723
724 <programlisting>
725 typedef struct ngx_queue_s ngx_queue_t;
726
727 struct ngx_queue_s {
728 ngx_queue_t *prev;
729 ngx_queue_t *next;
730 };
731 </programlisting>
732
733 <para>
734 The head queue node is not linked with any data. Before using, the list head
735 should be initialized with <literal>ngx_queue_init(q)</literal> call.
736 Queues support the following operations:
737 </para>
738
739 <para>
740 <list type="bullet">
741
742 <listitem>
743 <literal>ngx_queue_insert_head(h, x)</literal>,
744 <literal>ngx_queue_insert_tail(h, x)</literal> - insert a new node
745 </listitem>
746
747 <listitem>
748 <literal>ngx_queue_remove(x)</literal> - remove a queue node
749 </listitem>
750
751 <listitem>
752 <literal>ngx_queue_split(h, q, n)</literal> - split a queue at a node,
753 queue tail is returned in a separate queue
754 </listitem>
755
756 <listitem>
757 <literal>ngx_queue_add(h, n)</literal> - add second queue to the first queue
758 </listitem>
759
760 <listitem>
761 <literal>ngx_queue_head(h)</literal>,
762 <literal>ngx_queue_last(h)</literal> - get first or last queue node
763 </listitem>
764
765 <listitem>
766 <literal>ngx_queue_sentinel(h)</literal>
767 - get a queue sentinel object to end iteration at
768 </listitem>
769
770 <listitem>
771 <literal>ngx_queue_data(q, type, link)</literal> - get reference to the beginning of a
772 queue node data structure, considering the queue field offset in it
773 </listitem>
774
775 </list>
776 </para>
777
778 <para>
779 Example:
780 </para>
781
782
783 <programlisting>
784 typedef struct {
785 ngx_str_t value;
786 ngx_queue_t queue;
787 } ngx_foo_t;
788
789 ngx_foo_t *f;
790 ngx_queue_t values;
791
792 ngx_queue_init(&amp;values);
793
794 f = ngx_palloc(pool, sizeof(ngx_foo_t));
795 if (f == NULL) { /* error */ }
796 ngx_str_set(&amp;f->value, “foo”);
797
798 ngx_queue_insert_tail(&amp;values, f);
799
800 /* insert more nodes here */
801
802 for (q = ngx_queue_head(&amp;values);
803 q != ngx_queue_sentinel(&amp;values);
804 q = ngx_queue_next(q))
805 {
806 f = ngx_queue_data(q, ngx_foo_t, queue);
807
808 ngx_do_smth(&amp;f->value);
809 }
810 </programlisting>
811
812 </section>
813
814
815 <section name="Red-Black tree" id="red_black_tree">
816
817 <para>
818 The <literal>src/core/ngx_rbtree.h</literal> header file provides access to the
819 effective implementation of red-black trees.
820 </para>
821
822
823 <programlisting>
824 typedef struct {
825 ngx_rbtree_t rbtree;
826 ngx_rbtree_node_t sentinel;
827
828 /* custom per-tree data here */
829 } my_tree_t;
830
831 typedef struct {
832 ngx_rbtree_node_t rbnode;
833
834 /* custom per-node data */
835 foo_t val;
836 } my_node_t;
837 </programlisting>
838
839 <para>
840 To deal with a tree as a whole, you need two nodes: root and sentinel.
841 Typically, they are added to some custom structure, thus allowing to
842 organize your data into a tree which leaves contain a link to or embed
843 your data.
844 </para>
845
846 <para>
847 To initialize a tree:
848 </para>
849
850
851 <programlisting>
852 my_tree_t root;
853
854 ngx_rbtree_init(&amp;root.rbtree, &amp;root.sentinel, insert_value_function);
855 </programlisting>
856
857 <para>
858 The <literal>insert_value_function</literal> is a function that is
859 responsible for traversing the tree and inserting new values into correct
860 place.
861 For example, the <literal>ngx_str_rbtree_insert_value</literal> functions is
862 designed to deal with <literal>ngx_str_t</literal> type.
863 </para>
864
865
866 <programlisting>
867 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
868 ngx_rbtree_node_t *node,
869 ngx_rbtree_node_t *sentinel)
870 </programlisting>
871
872 <para>
873 Its arguments are pointers to a root node of an insertion, newly created node
874 to be added, and a tree sentinel.
875 </para>
876
877 <para>
878 The traversal is pretty straightforward and can be demonstrated with the
879 following lookup function pattern:
880 </para>
881
882
883 <programlisting>
884 my_node_t *
885 my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
886 {
887 ngx_int_t rc;
888 my_node_t *n;
889 ngx_rbtree_node_t *node, *sentinel;
890
891 node = rbtree->root;
892 sentinel = rbtree->sentinel;
893
894 while (node != sentinel) {
895
896 n = (my_node_t *) node;
897
898 if (hash != node->key) {
899 node = (hash &lt; node->key) ? node->left : node->right;
900 continue;
901 }
902
903 rc = compare(val, node->val);
904
905 if (rc &lt; 0) {
906 node = node->left;
907 continue;
908 }
909
910 if (rc > 0) {
911 node = node->right;
912 continue;
913 }
914
915 return n;
916 }
917
918 return NULL;
919 }
920 </programlisting>
921
922 <para>
923 The <literal>compare()</literal> is a classic comparator function returning
924 value less, equal or greater than zero. To speed up lookups and avoid comparing
925 user objects that can be big, integer hash field is used.
926 </para>
927
928 <para>
929 To add a node to a tree, allocate a new node, initialize it and call
930 <literal>ngx_rbtree_insert()</literal>:
931 </para>
932
933
934 <programlisting>
935 my_node_t *my_node;
936 ngx_rbtree_node_t *node;
937
938 my_node = ngx_palloc(...);
939 init_custom_data(&amp;my_node->val);
940
941 node = &amp;my_node->rbnode;
942 node->key = create_key(my_node->val);
943
944 ngx_rbtree_insert(&amp;root->rbtree, node);
945 </programlisting>
946
947 <para>
948 to remove a node:
949 </para>
950
951
952 <programlisting>
953 ngx_rbtree_delete(&amp;root->rbtree, node);
954 </programlisting>
955
956 </section>
957
958
959 </section>
960
961
962 <section name="Memory management" id="memory_management">
963
964
965 <section name="Heap" id="heap">
966
967 <para>
968 To allocate memory from system heap, the following functions are provided by
969 nginx:
970 </para>
971
972 <para>
973 <list type="bullet">
974
975 <listitem>
976 <literal>ngx_alloc(size, log)</literal> - allocate memory from system heap.
977 This is a wrapper around <literal>malloc()</literal> with logging support.
978 Allocation error and debugging information is logged to <literal>log</literal>
979 </listitem>
980
981 <listitem>
982 <literal>ngx_calloc(size, log)</literal> - same as
983 <literal>ngx_alloc()</literal>, but memory is filled with zeroes after
984 allocation
985 </listitem>
986
987 <listitem>
988 <literal>ngx_memalign(alignment, size, log)</literal> - allocate aligned memory
989 from system heap. This is a wrapper around <literal>posix_memalign()</literal>
990 on those platforms which provide it.
991 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
992 provides maximum alignment
993 </listitem>
994
995 <listitem>
996 <literal>ngx_free(p)</literal> - free allocated memory.
997 This is a wrapper around <literal>free()</literal>
998 </listitem>
999
1000 </list>
1001 </para>
1002
1003 </section>
1004
1005
1006 <section name="Pool" id="pool">
1007
1008 <para>
1009 Most nginx allocations are done in pools. Memory allocated in an nginx pool is
1010 freed automatically when the pool in destroyed. This provides good
1011 allocation performance and makes memory control easy.
1012 </para>
1013
1014 <para>
1015 A pool internally allocates objects in continuous blocks of memory. Once a
1016 block is full, a new one is allocated and added to the pool memory
1017 block list. When a large allocation is requested which does not fit into
1018 a block, such allocation is forwarded to the system allocator and the
1019 returned pointer is stored in the pool for further deallocation.
1020 </para>
1021
1022 <para>
1023 Nginx pool has the type <literal>ngx_pool_t</literal>.
1024 The following operations are supported:
1025 </para>
1026
1027 <para>
1028 <list type="bullet">
1029
1030 <listitem>
1031 <literal>ngx_create_pool(size, log)</literal> - create a pool with given
1032 block size. The pool object returned is allocated in the pool as well.
1033 </listitem>
1034
1035 <listitem>
1036 <literal>ngx_destroy_pool(pool)</literal> - free all pool memory, including
1037 the pool object itself.
1038 </listitem>
1039
1040 <listitem>
1041 <literal>ngx_palloc(pool, size)</literal> - allocate aligned memory from pool
1042 </listitem>
1043
1044 <listitem>
1045 <literal>ngx_pcalloc(pool, size)</literal> - allocated aligned memory
1046 from pool and fill it with zeroes
1047 </listitem>
1048
1049 <listitem>
1050 <literal>ngx_pnalloc(pool, size)</literal> - allocate unaligned memory from pool.
1051 Mostly used for allocating strings
1052 </listitem>
1053
1054 <listitem>
1055 <literal>ngx_pfree(pool, p)</literal> - free memory, previously allocated
1056 in the pool.
1057 Only allocations, forwarded to the system allocator, can be freed.
1058 </listitem>
1059
1060 </list>
1061 </para>
1062
1063 <programlisting>
1064 u_char *p;
1065 ngx_str_t *s;
1066 ngx_pool_t *pool;
1067
1068 pool = ngx_create_pool(1024, log);
1069 if (pool == NULL) { /* error */ }
1070
1071 s = ngx_palloc(pool, sizeof(ngx_str_t));
1072 if (s == NULL) { /* error */ }
1073 ngx_str_set(s, “foo”);
1074
1075 p = ngx_pnalloc(pool, 3);
1076 if (p == NULL) { /* error */ }
1077 ngx_memcpy(p, “foo”, 3);
1078 </programlisting>
1079
1080 <para>
1081 Since chain links <literal>ngx_chain_t</literal> are actively used in nginx,
1082 nginx pool provides a way to reuse them.
1083 The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a
1084 list of previously allocated links ready for reuse. For efficient allocation of
1085 a chain link in a pool, the function
1086 <literal>ngx_alloc_chain_link(pool)</literal> should be used.
1087 This function looks up a free chain link in the pool list and only if it's
1088 empty allocates a new one. To free a link <literal>ngx_free_chain(pool, cl)</literal>
1089 should be called.
1090 </para>
1091
1092 <para>
1093 Cleanup handlers can be registered in a pool.
1094 Cleanup handler is a callback with an argument which is called when pool is
1095 destroyed.
1096 Pool is usually tied with a specific nginx object (like HTTP request) and
1097 destroyed in the end of that object’s lifetime, releasing the object itself.
1098 Registering a pool cleanup is a convinient way to release resources, close file
1099 descriptors or make final adjustments to shared data, associated with the main
1100 object.
1101 </para>
1102
1103 <para>
1104 A pool cleanup is registered by calling <literal>ngx_pool_cleanup_add(pool,
1105 size)</literal> which returns <literal>ngx_pool_cleanup_t</literal> pointer to
1106 be filled by the caller. The <literal>size</literal> argument allows allocating
1107 context for the cleanup handler.
1108 </para>
1109
1110
1111 <programlisting>
1112 ngx_pool_cleanup_t *cln;
1113
1114 cln = ngx_pool_cleanup_add(pool, 0);
1115 if (cln == NULL) { /* error */ }
1116
1117 cln->handler = ngx_my_cleanup;
1118 cln->data = “foo”;
1119
1120 ...
1121
1122 static void
1123 ngx_my_cleanup(void *data)
1124 {
1125 u_char *msg = data;
1126
1127 ngx_do_smth(msg);
1128 }
1129 </programlisting>
1130
1131 </section>
1132
1133
1134 <section name="Shared memory" id="shared_memory">
1135
1136 <para>
1137 Shared memory is used by nginx to share common data between processes.
1138 Function <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> adds a
1139 new shared memory entry <literal>ngx_shm_zone_t</literal> to the cycle. The
1140 function receives <literal>name</literal> and <literal>size</literal> of the
1141 zone.
1142 Each shared zone must have a unique name.
1143 If a shared zone entry with the provided name exists, the old zone entry is
1144 reused, if its tag value matches too.
1145 Mismatched tag is considered an error.
1146 Usually, the address of the module structure is passed as tag, making it
1147 possible to reuse shared zones by name within one nginx module.
1148 </para>
1149
1150 <para>
1151 The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the
1152 following fields:
1153 </para>
1154
1155 <para>
1156 <list type="bullet">
1157
1158 <listitem>
1159 <literal>init</literal> - initialization callback, called after shared zone is
1160 mapped to actual memory
1161 </listitem>
1162
1163 <listitem>
1164 <literal>data</literal> - data context, used to pass arbitrary data to the
1165 <literal>init</literal> callback
1166 </listitem>
1167
1168 <listitem>
1169 <literal>noreuse</literal> - flag, disabling shared zone reuse from the
1170 old cycle
1171 </listitem>
1172
1173 <listitem>
1174 <literal>tag</literal> - shared zone tag
1175 </listitem>
1176
1177 <listitem>
1178 <literal>shm</literal> - platform-specific object of type
1179 <literal>ngx_shm_t</literal>, having at least the following fields:
1180 <list type="bullet">
1181
1182 <listitem>
1183 <literal>addr</literal> - mapped shared memory address, initially NULL
1184 </listitem>
1185
1186 <listitem>
1187 <literal>size</literal> - shared memory size
1188 </listitem>
1189
1190 <listitem>
1191 <literal>name</literal> - shared memory name
1192 </listitem>
1193
1194 <listitem>
1195 <literal>log</literal> - shared memory log
1196 </listitem>
1197
1198 <listitem>
1199 <literal>exists</literal> - flag, showing that shared memory was inherited
1200 from the master process (Windows-specific)
1201 </listitem>
1202
1203 </list>
1204 </listitem>
1205
1206 </list>
1207 </para>
1208
1209 <para>
1210 Shared zone entries are mapped to actual memory in
1211 <literal>ngx_init_cycle()</literal> after configuration is parsed.
1212 On POSIX systems, <literal>mmap()</literal> syscall is used to create shared
1213 anonymous mapping.
1214 On Windows, <literal>CreateFileMapping()/MapViewOfFileEx()</literal> pair is
1215 used.
1216 </para>
1217
1218 <para>
1219 For allocating in shared memory, nginx provides slab pool
1220 <literal>ngx_slab_pool_t</literal>.
1221 In each nginx shared zone, a slab pool is automatically created for allocating
1222 memory in that zone.
1223 The pool is located in the beginning of the shared zone and can be accessed by
1224 the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>.
1225 Allocation in shared zone is done by calling one of the functions
1226 <literal>ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size)</literal>.
1227 Memory is freed by calling <literal>ngx_slab_free(pool, p)</literal>.
1228 </para>
1229
1230 <para>
1231 Slab pool divides all shared zone into pages.
1232 Each page is used for allocating objects of the same size.
1233 Only the sizes which are powers of 2, and not less than 8, are considered.
1234 Other sizes are rounded up to one of these values.
1235 For each page, a bitmask is kept, showing which blocks within that page are in
1236 use and which are free for allocation.
1237 For sizes greater than half-page (usually, 2048 bytes), allocation is done by
1238 entire pages.
1239 </para>
1240
1241 <para>
1242 To protect data in shared memory from concurrent access, mutex is available in
1243 the <literal>mutex</literal> field of <literal>ngx_slab_pool_t</literal>.
1244 The mutex is used by the slab pool while allocating and freeing memory.
1245 However, it can be used to protect any other user data structures,
1246 allocated in the shared zone.
1247 Locking is done by calling
1248 <literal>ngx_shmtx_lock(&amp;shpool->mutex)</literal>, unlocking is done by
1249 calling <literal>ngx_shmtx_unlock(&amp;shpool->mutex)</literal>.
1250 </para>
1251
1252
1253 <programlisting>
1254 ngx_str_t name;
1255 ngx_foo_ctx_t *ctx;
1256 ngx_shm_zone_t *shm_zone;
1257
1258 ngx_str_set(&amp;name, "foo");
1259
1260 /* allocate shared zone context */
1261 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
1262 if (ctx == NULL) {
1263 /* error */
1264 }
1265
1266 /* add an entry for 65k shared zone */
1267 shm_zone = ngx_shared_memory_add(cf, &amp;name, 65536, &amp;ngx_foo_module);
1268 if (shm_zone == NULL) {
1269 /* error */
1270 }
1271
1272 /* register init callback and context */
1273 shm_zone->init = ngx_foo_init_zone;
1274 shm_zone->data = ctx;
1275
1276
1277 ...
1278
1279
1280 static ngx_int_t
1281 ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
1282 {
1283 ngx_foo_ctx_t *octx = data;
1284
1285 size_t len;
1286 ngx_foo_ctx_t *ctx;
1287 ngx_slab_pool_t *shpool;
1288
1289 value = shm_zone->data;
1290
1291 if (octx) {
1292 /* reusing a shared zone from old cycle */
1293 ctx->value = octx->value;
1294 return NGX_OK;
1295 }
1296
1297 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
1298
1299 if (shm_zone->shm.exists) {
1300 /* initialize shared zone context in Windows nginx worker */
1301 ctx->value = shpool->data;
1302 return NGX_OK;
1303 }
1304
1305 /* initialize shared zone */
1306
1307 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
1308 if (ctx->value == NULL) {
1309 return NGX_ERROR;
1310 }
1311
1312 shpool->data = ctx->value;
1313
1314 return NGX_OK;
1315 }
1316 </programlisting>
1317
1318 </section>
1319
1320
1321 </section>
1322
1323
1324 <section name="Logging" id="logging">
1325
1326 <para>
1327 For logging nginx code uses <literal>ngx_log_t</literal> objects.
1328 Nginx logger provides support for several types of output:
1329
1330 <list type="bullet">
1331
1332 <listitem>
1333 stderr - logging to standard error output
1334 </listitem>
1335
1336 <listitem>
1337 file - logging to file
1338 </listitem>
1339
1340 <listitem>
1341 syslog - logging to syslog
1342 </listitem>
1343
1344 <listitem>
1345 memory - logging to internal memory storage for development purposes.
1346 The memory could be accessed later with debugger
1347 </listitem>
1348
1349 </list>
1350 </para>
1351
1352 <para>
1353 A logger instance may actually be a chain of loggers, linked to each other with
1354 the <literal>next</literal> field.
1355 Each message is written to all loggers in chain.
1356 </para>
1357
1358 <para>
1359 Each logger has an error level which limits the messages written to that log.
1360 The following error levels are supported by nginx:
1361 </para>
1362
1363 <para>
1364 <list type="bullet">
1365
1366 <listitem>
1367 <literal>NGX_LOG_EMERG</literal>
1368 </listitem>
1369
1370 <listitem>
1371 <literal>NGX_LOG_ALERT</literal>
1372 </listitem>
1373
1374 <listitem>
1375 <literal>NGX_LOG_CRIT</literal>
1376 </listitem>
1377
1378 <listitem>
1379 <literal>NGX_LOG_ERR</literal>
1380 </listitem>
1381
1382 <listitem>
1383 <literal>NGX_LOG_WARN</literal>
1384 </listitem>
1385
1386 <listitem>
1387 <literal>NGX_LOG_NOTICE</literal>
1388 </listitem>
1389
1390 <listitem>
1391 <literal>NGX_LOG_INFO</literal>
1392 </listitem>
1393
1394 <listitem>
1395 <literal>NGX_LOG_DEBUG</literal>
1396 </listitem>
1397
1398 </list>
1399 </para>
1400
1401 <para>
1402 For debug logging, debug mask is checked as well. The following debug masks
1403 exist:
1404 </para>
1405
1406 <para>
1407 <list type="bullet">
1408
1409 <listitem>
1410 <literal>NGX_LOG_DEBUG_CORE</literal>
1411 </listitem>
1412
1413 <listitem>
1414 <literal>NGX_LOG_DEBUG_ALLOC</literal>
1415 </listitem>
1416
1417 <listitem>
1418 <literal>NGX_LOG_DEBUG_MUTEX</literal>
1419 </listitem>
1420
1421 <listitem>
1422 <literal>NGX_LOG_DEBUG_EVENT</literal>
1423 </listitem>
1424
1425 <listitem>
1426 <literal>NGX_LOG_DEBUG_HTTP</literal>
1427 </listitem>
1428
1429 <listitem>
1430 <literal>NGX_LOG_DEBUG_MAIL</literal>
1431 </listitem>
1432
1433 <listitem>
1434 <literal>NGX_LOG_DEBUG_STREAM</literal>
1435 </listitem>
1436
1437 </list>
1438 </para>
1439
1440 <para>
1441 Normally, loggers are created by existing nginx code from
1442 <literal>error_log</literal> directives and are available at nearly every stage
1443 of processing in cycle, configuration, client connection and other objects.
1444 </para>
1445
1446 <para>
1447 Nginx provides the following logging macros:
1448 </para>
1449
1450 <para>
1451 <list type="bullet">
1452
1453 <listitem>
1454 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> - error logging
1455 </listitem>
1456
1457 <listitem>
1458 <literal>ngx_log_debug0(level, log, err, fmt)</literal>,
1459 <literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc - debug
1460 logging, up to 8 formatting arguments are supported
1461 </listitem>
1462
1463 </list>
1464 </para>
1465
1466 <para>
1467 A log message is formatted in a buffer of size
1468 <literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack.
1469 The message is prepended with error level, process PID, connection id (stored
1470 in <literal>log->connection</literal>) and system error text.
1471 For non-debug messages <literal>log->handler</literal> is called as well to
1472 prepend more specific information to the log message.
1473 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
1474 handler to log client and server addresses, current action (stored in
1475 <literal>log->action</literal>), client request line, server name etc.
1476 </para>
1477
1478 <para>
1479 Example:
1480 </para>
1481
1482
1483 <programlisting>
1484 /* specify what is currently done */
1485 log->action = "sending mp4 to client”;
1486
1487 /* error and debug log */
1488 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
1489 closed connection”);
1490
1491 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
1492 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
1493 </programlisting>
1494
1495 <para>
1496 Logging result:
1497 </para>
1498
1499
1500 <programlisting>
1501 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
1502 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
1503 2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
1504 </programlisting>
1505
1506 </section>
1507
1508
1509 <section name="Cycle" id="cycle">
1510
1511 <para>
1512 Cycle object keeps nginx runtime context, created from a specific
1513 configuration.
1514 The type of the cycle is <literal>ngx_cycle_t</literal>.
1515 Upon configuration reload a new cycle is created from the new version of nginx
1516 configuration.
1517 The old cycle is usually deleted after a new one is successfully created.
1518 Currently active cycle is held in the <literal>ngx_cycle</literal> global
1519 variable and is inherited by newly started nginx workers.
1520 </para>
1521
1522 <para>
1523 A cycle is created by the function <literal>ngx_init_cycle()</literal>.
1524 The function receives the old cycle as the argument.
1525 It's used to locate the configuration file and inherit as much resources as
1526 possible from the old cycle to keep nginx running smoothly.
1527 When nginx starts, a fake cycle called "init cycle" is created and is then
1528 replaced by a normal cycle, built from configuration.
1529 </para>
1530
1531 <para>
1532 Some members of the cycle:
1533 </para>
1534
1535 <para>
1536 <list type="bullet">
1537
1538 <listitem>
1539 <literal>pool</literal> - cycle pool. Created for each new cycle
1540 </listitem>
1541
1542 <listitem>
1543 <literal>log</literal> - cycle log. Initially, this log is inherited from the
1544 old cycle.
1545 After reading configuration, this member is set to point to
1546 <literal>new_log</literal>
1547 </listitem>
1548
1549 <listitem>
1550 <literal>new_log</literal> - cycle log, created by the configuration.
1551 It's affected by the root scope <literal>error_log</literal> directive
1552 </listitem>
1553
1554 <listitem>
1555 <literal>connections</literal>, <literal>connections_n</literal> - per-worker
1556 array of connections of type <literal>ngx_connection_t</literal>, created by
1557 the event module while initializing each nginx worker.
1558 The number of connections is set by the <literal>worker_connections</literal>
1559 directive
1560 </listitem>
1561
1562 <listitem>
1563 <literal>free_connections</literal>,
1564 <literal>free_connections_n</literal> - the and number of currently available
1565 connections.
1566 If no connections are available, nginx worker refuses to accept new clients
1567 </listitem>
1568
1569 <listitem>
1570 <literal>files</literal>, <literal>files_n</literal> - array for mapping file
1571 descriptors to nginx connections.
1572 This mapping is used by the event modules, having the
1573 <literal>NGX_USE_FD_EVENT</literal> flag (currently, it's poll and devpoll)
1574 </listitem>
1575
1576 <listitem>
1577 <literal>conf_ctx</literal> - array of core module configurations.
1578 The configurations are created and filled while reading nginx configuration
1579 files
1580 </listitem>
1581
1582 <listitem>
1583 <literal>modules</literal>, <literal>modules_n</literal> - array of modules
1584 <literal>ngx_module_t</literal>, both static and dynamic, loaded by current
1585 configuration
1586 </listitem>
1587
1588 <listitem>
1589 <literal>listening</literal> - array of listening objects
1590 <literal>ngx_listening_t</literal>.
1591 Listening objects are normally added by the the <literal>listen</literal>
1592 directive of different modules which call the
1593 <literal>ngx_create_listening()</literal> function.
1594 Based on listening objects, listen sockets are created by nginx
1595 </listitem>
1596
1597 <listitem>
1598 <literal>paths</literal> - array of paths <literal>ngx_path_t</literal>.
1599 Paths are added by calling the function <literal>ngx_add_path()</literal> from
1600 modules which are going to operate on certain directories.
1601 These directories are created by nginx after reading configuration, if missing.
1602 Moreover, two handlers can be added for each path:
1603
1604 <list type="bullet">
1605
1606 <listitem>
1607 path loader - executed only once in 60 seconds after starting or reloading
1608 nginx. Normally, reads the directory and stores data in nginx shared
1609 memory. The handler is called from a dedicated nginx process "nginx
1610 cache loader"
1611 </listitem>
1612
1613 <listitem>
1614 path manager - executed periodically. Normally, removes old files from the
1615 directory and reflects these changes in nginx memory. The handler is
1616 called from a dedicated nginx process "nginx cache manager"
1617 </listitem>
1618
1619 </list>
1620 </listitem>
1621
1622 <listitem>
1623 <literal>open_files</literal> - list of <literal>ngx_open_file_t</literal>
1624 objects.
1625 An open file object is created by calling the function
1626 <literal>ngx_conf_open_file()</literal>.
1627 After reading configuration nginx opens all files from the
1628 <literal>open_files</literal> list and stores file descriptors in the
1629 <literal>fd</literal> field of each open file object.
1630 The files are opened in append mode and created if missing.
1631 The files from this list are reopened by nginx workers upon receiving the
1632 reopen signal (usually it's <literal>USR1</literal>).
1633 In this case the <literal>fd</literal> fields are changed to new descriptors.
1634 The open files are currently used for logging
1635 </listitem>
1636
1637 <listitem>
1638 <literal>shared_memory</literal> - list of shared memory zones, each added by
1639 calling the <literal>ngx_shared_memory_add()</literal> function.
1640 Shared zones are mapped to the same address range in all nginx processes and
1641 are used to share common data, for example HTTP cache in-memory tree
1642 </listitem>
1643
1644 </list>
1645 </para>
1646
1647 </section>
1648
1649 <section name="Buffer" id="buffer">
1650
1651 <para>
1652 For input/output operations, nginx provides the buffer type
1653 <literal>ngx_buf_t</literal>.
1654 Normally, it's used to hold data to be written to a destination or read from a
1655 source.
1656 Buffer can reference data in memory and in file.
1657 Technically it's possible that a buffer references both at the same time.
1658 Memory for the buffer is allocated separately and is not related to the buffer
1659 structure <literal>ngx_buf_t</literal>.
1660 </para>
1661
1662 <para>
1663 The structure <literal>ngx_buf_t</literal> has the following fields:
1664 </para>
1665
1666 <para>
1667 <list type="bullet">
1668
1669 <listitem>
1670 <literal>start</literal>, <literal>end</literal> - the boundaries of memory
1671 block, allocated for the buffer
1672 </listitem>
1673
1674 <listitem>
1675 <literal>pos</literal>, <literal>last</literal> - memory buffer boundaries,
1676 normally a subrange of <literal>start</literal> .. <literal>end</literal>
1677 </listitem>
1678
1679 <listitem>
1680 <literal>file_pos</literal>, <literal>file_last</literal> - file buffer
1681 boundaries, these are offsets from the beginning of the file
1682 </listitem>
1683
1684 <listitem>
1685 <literal>tag</literal> - unique value, used to distinguish buffers, created by
1686 different nginx module, usually, for the purpose of buffer reuse
1687 </listitem>
1688
1689 <listitem>
1690 <literal>file</literal> - file object
1691 </listitem>
1692
1693 <listitem>
1694 <literal>temporary</literal> - flag, meaning that the buffer references
1695 writable memory
1696 </listitem>
1697
1698 <listitem>
1699 <literal>memory</literal> - flag, meaning that the buffer references read-only
1700 memory
1701 </listitem>
1702
1703 <listitem>
1704 <literal>in_file</literal> - flag, meaning that current buffer references data
1705 in a file
1706 </listitem>
1707
1708 <listitem>
1709 <literal>flush</literal> - flag, meaning that all data prior to this buffer
1710 should be flushed
1711 </listitem>
1712
1713 <listitem>
1714 <literal>recycled</literal> - flag, meaning that the buffer can be reused and
1715 should be consumed as soon as possible
1716 </listitem>
1717
1718 <listitem>
1719 <literal>sync</literal> - flag, meaning that the buffer carries no data or
1720 special signal like <literal>flush</literal> or <literal>last_buf</literal>.
1721 Normally, such buffers are considered an error by nginx. This flags allows
1722 skipping the error checks
1723 </listitem>
1724
1725 <listitem>
1726 <literal>last_buf</literal> - flag, meaning that current buffer is the last in
1727 output
1728 </listitem>
1729
1730 <listitem>
1731 <literal>last_in_chain</literal> - flag, meaning that there's no more data
1732 buffers in a (sub)request
1733 </listitem>
1734
1735 <listitem>
1736 <literal>shadow</literal> - reference to another buffer, related to the current
1737 buffer. Usually current buffer uses data from the shadow buffer. Once current
1738 buffer is consumed, the shadow buffer should normally also be marked as
1739 consumed
1740 </listitem>
1741
1742 <listitem>
1743 <literal>last_shadow</literal> - flag, meaning that current buffer is the last
1744 buffer, referencing a particular shadow buffer
1745 </listitem>
1746
1747 <listitem>
1748 <literal>temp_file</literal> - flag, meaning that the buffer is in a temporary
1749 file
1750 </listitem>
1751
1752 </list>
1753 </para>
1754
1755 <para>
1756 For input and output buffers are linked in chains.
1757 Chain is a sequence of chain links <literal>ngx_chain_t</literal>, defined as
1758 follows:
1759 </para>
1760
1761
1762 <programlisting>
1763 typedef struct ngx_chain_s ngx_chain_t;
1764
1765 struct ngx_chain_s {
1766 ngx_buf_t *buf;
1767 ngx_chain_t *next;
1768 };
1769 </programlisting>
1770
1771 <para>
1772 Each chain link keeps a reference to its buffer and a reference to the next
1773 chain link.
1774 </para>
1775
1776 <para>
1777 Example of using buffers and chains:
1778 </para>
1779
1780
1781 <programlisting>
1782 ngx_chain_t *
1783 ngx_get_my_chain(ngx_pool_t *pool)
1784 {
1785 ngx_buf_t *b;
1786 ngx_chain_t *out, *cl, **ll;
1787
1788 /* first buf */
1789 cl = ngx_alloc_chain_link(pool);
1790 if (cl == NULL) { /* error */ }
1791
1792 b = ngx_calloc_buf(pool);
1793 if (b == NULL) { /* error */ }
1794
1795 b->start = (u_char *) "foo";
1796 b->pos = b->start;
1797 b->end = b->start + 3;
1798 b->last = b->end;
1799 b->memory = 1; /* read-only memory */
1800
1801 cl->buf = b;
1802 out = cl;
1803 ll = &amp;cl->next;
1804
1805 /* second buf */
1806 cl = ngx_alloc_chain_link(pool);
1807 if (cl == NULL) { /* error */ }
1808
1809 b = ngx_create_temp_buf(pool, 3);
1810 if (b == NULL) { /* error */ }
1811
1812 b->last = ngx_cpymem(b->last, "foo", 3);
1813
1814 cl->buf = b;
1815 cl->next = NULL;
1816 *ll = cl;
1817
1818 return out;
1819 }
1820 </programlisting>
1821
1822 </section>
1823
1824
1825 <section name="Networking" id="networking">
1826
1827
1828 <!--
1829 <section name="Network data types" id="network_data_types">
1830
1831 <para>
1832 TBD: ngx_addr_t, ngx_url_t, ngx_socket_t, ngx_sockaddr_t, parse url, parse
1833 address...
1834 </para>
1835
1836 </section>
1837 -->
1838
1839 <section name="Connection" id="connection">
1840
1841 <para>
1842 Connection type <literal>ngx_connection_t</literal> is a wrapper around a
1843 socket descriptor. Some of the structure fields are:
1844 </para>
1845
1846 <para>
1847 <list type="bullet">
1848
1849 <listitem>
1850 <literal>fd</literal> - socket descriptor
1851 </listitem>
1852
1853 <listitem>
1854 <literal>data</literal> - arbitrary connection context.
1855 Normally, a pointer to a higher level object, built on top of the connection,
1856 like HTTP request or Stream session
1857 </listitem>
1858
1859 <listitem>
1860 <literal>read</literal>, <literal>write</literal> - read and write events for
1861 the connection
1862 </listitem>
1863
1864 <listitem>
1865 <literal>recv</literal>, <literal>send</literal>,
1866 <literal>recv_chain</literal>, <literal>send_chain</literal> - I/O operations
1867 for the connection
1868 </listitem>
1869
1870 <listitem>
1871 <literal>pool</literal> - connection pool
1872 </listitem>
1873
1874 <listitem>
1875 <literal>log</literal> - connection log
1876 </listitem>
1877
1878 <listitem>
1879 <literal>sockaddr</literal>, <literal>socklen</literal>,
1880 <literal>addr_text</literal> - remote socket address in binary and text forms
1881 </listitem>
1882
1883 <listitem>
1884 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> - local
1885 socket address in binary form.
1886 Initially, these fields are empty.
1887 Function <literal>ngx_connection_local_sockaddr()</literal> should be used to
1888 get socket local address
1889 </listitem>
1890
1891 <listitem>
1892 <literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal>
1893 - PROXY protocol client address and port, if PROXY protocol is enabled for the
1894 connection
1895 </listitem>
1896
1897 <listitem>
1898 <literal>ssl</literal> - nginx connection SSL context
1899 </listitem>
1900
1901 <listitem>
1902 <literal>reusable</literal> - flag, meaning, that the connection is at the
1903 state, when it can be reused
1904 </listitem>
1905
1906 <listitem>
1907 <literal>close</literal> - flag, meaning, that the connection is being reused
1908 and should be closed
1909 </listitem>
1910
1911 </list>
1912 </para>
1913
1914 <para>
1915 An nginx connection can transparently encapsulate SSL layer.
1916 In this case the connection <literal>ssl</literal> field holds a pointer to an
1917 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
1918 for the connection, including <literal>SSL_CTX</literal> and
1919 <literal>SSL</literal>.
1920 The handlers <literal>recv</literal>, <literal>send</literal>,
1921 <literal>recv_chain</literal>, <literal>send_chain</literal> are set as well to
1922 SSL functions.
1923 </para>
1924
1925 <para>
1926 The number of connections per nginx worker is limited by the
1927 <literal>worker_connections</literal> value.
1928 All connection structures are pre-created when a worker starts and stored in
1929 the <literal>connections</literal> field of the cycle object.
1930 To reach out for a connection structure, <literal>ngx_get_connection(s,
1931 log)</literal> function is used.
1932 The function receives a socket descriptor <literal>s</literal> which needs to
1933 be wrapped in a connection structure.
1934 </para>
1935
1936 <para>
1937 Since the number of connections per worker is limited, nginx provides a
1938 way to grab connections which are currently in use.
1939 To enable or disable reuse of a connection, function
1940 <literal>ngx_reusable_connection(c, reusable)</literal> is called.
1941 Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the
1942 <literal>reuse</literal> flag of the connection structure and inserts the
1943 connection in the <literal>reusable_connections_queue</literal> of the cycle.
1944 Whenever <literal>ngx_get_connection()</literal> finds out there are no
1945 available connections in the <literal>free_connections</literal> list of the
1946 cycle, it calls <literal>ngx_drain_connections()</literal> to release a
1947 specific number of reusable connections.
1948 For each such connection, the <literal>close</literal> flag is set and its read
1949 handler is called which is supposed to free the connection by calling
1950 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
1951 To exit the state when a connection can be reused
1952 <literal>ngx_reusable_connection(c, 0)</literal> is called.
1953 An example of reusable connections in nginx is HTTP client connections which
1954 are marked as reusable until some data is received from the client.
1955 </para>
1956
1957 </section>
1958
1959
1960 </section>
1961
1962
1963 <section name="Events" id="events">
1964
1965
1966 <section name="Event" id="event">
1967
1968 <para>
1969 Event object <literal>ngx_event_t</literal> in nginx provides a way to be
1970 notified of a specific event happening.
1971 </para>
1972
1973 <para>
1974 Some of the fields of the <literal>ngx_event_t</literal> are:
1975 </para>
1976
1977 <para>
1978 <list type="bullet">
1979
1980 <listitem>
1981 <literal>data</literal> - arbitrary event context, used in event handler,
1982 usually, a pointer to a connection, tied with the event
1983 </listitem>
1984
1985 <listitem>
1986 <literal>handler</literal> - callback function to be invoked when the event
1987 happens
1988 </listitem>
1989
1990 <listitem>
1991 <literal>write</literal> - flag, meaning that this is the write event.
1992 Used to distinguish between read and write events
1993 </listitem>
1994
1995 <listitem>
1996 <literal>active</literal> - flag, meaning that the event is registered for
1997 receiving I/O notifications, normally from notification mechanisms like epoll,
1998 kqueue, poll
1999 </listitem>
2000
2001 <listitem>
2002 <literal>ready</literal> - flag, meaning that the event has received an
2003 I/O notification
2004 </listitem>
2005
2006 <listitem>
2007 <literal>delayed</literal> - flag, meaning that I/O is delayed due to rate
2008 limiting
2009 </listitem>
2010
2011 <listitem>
2012 <literal>timer</literal> - Red-Black tree node for inserting the event into
2013 the timer tree
2014 </listitem>
2015
2016 <listitem>
2017 <literal>timer_set</literal> - flag, meaning that the event timer is set,
2018 but not yet expired
2019 </listitem>
2020
2021 <listitem>
2022 <literal>timedout</literal> - flag, meaning that the event timer has expired
2023 </listitem>
2024
2025 <listitem>
2026 <literal>eof</literal> - read event flag, meaning that the eof has happened
2027 while reading data
2028 </listitem>
2029
2030 <listitem>
2031 <literal>pending_eof</literal> - flag, meaning that the eof is pending on the
2032 socket, even though there may be some data available before it.
2033 The flag is delivered via <literal>EPOLLRDHUP</literal> epoll event or
2034 <literal>EV_EOF</literal> kqueue flag
2035 </listitem>
2036
2037 <listitem>
2038 <literal>error</literal> - flag, meaning that an error has happened while
2039 reading (for read event) or writing (for write event)
2040 </listitem>
2041
2042 <listitem>
2043 <literal>cancelable</literal> - timer event flag, meaning that the event
2044 handler should be called while performing nginx worker graceful shutdown, event
2045 though event timeout has not yet expired. The flag provides a way to finalize
2046 certain activities, for example, flush log files
2047 </listitem>
2048
2049 <listitem>
2050 <literal>posted</literal> - flag, meaning that the event is posted to queue
2051 </listitem>
2052
2053 <listitem>
2054 <literal>queue</literal> - queue node for posting the event to a queue
2055 </listitem>
2056
2057 </list>
2058 </para>
2059
2060 </section>
2061
2062
2063 <section name="I/O events" id="i_o_events">
2064
2065 <para>
2066 Each connection, received with the
2067 <literal>ngx_get_connection()</literal> call, has two events attached to it:
2068 <literal>c->read</literal> and <literal>c->write</literal>.
2069 These events are used to receive notifications about the socket being ready for
2070 reading or writing.
2071 All such events operate in Edge-Triggered mode, meaning that they only trigger
2072 notifications when the state of the socket changes.
2073 For example, doing a partial read on a socket will not make nginx deliver a
2074 repeated read notification until more data arrive in the socket.
2075 Even when the underlying I/O notification mechanism is essentially
2076 Level-Triggered (poll, select etc), nginx will turn the notifications into
2077 Edge-Triggered.
2078 To make nginx event notifications consistent across all notifications systems
2079 on different platforms, it's required, that the functions
2080 <literal>ngx_handle_read_event(rev, flags)</literal> and
2081 <literal>ngx_handle_read_event(wev,flags)</literal> are called after handling
2082 an I/O socket notification or calling any I/O functions on that socket.
2083 Normally, these functions are called once in the end of each read or write
2084 event handler.
2085 </para>
2086
2087 </section>
2088
2089
2090 <section name="Timer events" id="timer_events">
2091
2092 <para>
2093 An event can be set to notify a timeout expiration.
2094 The function <literal>ngx_add_timer(ev, timer)</literal> sets a timeout for an
2095 event, <literal>ngx_del_timer(ev)</literal> deletes a previously set timeout.
2096 Timeouts currently set for all existing events, are kept in a global timeout
2097 Red-Black tree <literal>ngx_event_timer_rbtree</literal>.
2098 The key in that tree has the type <literal>ngx_msec_t</literal> and is the time
2099 in milliseconds since the beginning of January 1, 1970 (modulus
2100 <literal>ngx_msec_t</literal> max value) at which the event should expire.
2101 The tree structure provides fast inserting and deleting operations, as well as
2102 accessing the nearest timeouts.
2103 The latter is used by nginx to find out for how long to wait for I/O events
2104 and for expiring timeout events afterwards.
2105 </para>
2106
2107 </section>
2108
2109
2110 <section name="Posted events" id="posted_events">
2111
2112 <para>
2113 An event can be posted which means that its handler will be called at some
2114 point later within the current event loop iteration.
2115 Posting events is a good practice for simplifying code and escaping stack
2116 overflows.
2117 Posted events are held in a post queue.
2118 The macro <literal>ngx_post_event(ev, q)</literal> posts the event
2119 <literal>ev</literal> to the post queue <literal>q</literal>.
2120 Macro <literal>ngx_delete_posted_event(ev)</literal> deletes the event
2121 <literal>ev</literal> from whatever queue it's currently posted.
2122 Normally, events are posted to the <literal>ngx_posted_events</literal> queue.
2123 This queue is processed late in the event loop - after all I/O and timer
2124 events are already handled.
2125 The function <literal>ngx_event_process_posted()</literal> is called to process
2126 an event queue.
2127 This function calls event handlers until the queue is not empty. This means
2128 that a posted event handler can post more events to be processed within the
2129 current event loop iteration.
2130 </para>
2131
2132 <para>
2133 Example:
2134 </para>
2135
2136
2137 <programlisting>
2138 void
2139 ngx_my_connection_read(ngx_connection_t *c)
2140 {
2141 ngx_event_t *rev;
2142
2143 rev = c->read;
2144
2145 ngx_add_timer(rev, 1000);
2146
2147 rev->handler = ngx_my_read_handler;
2148
2149 ngx_my_read(rev);
2150 }
2151
2152
2153 void
2154 ngx_my_read_handler(ngx_event_t *rev)
2155 {
2156 ssize_t n;
2157 ngx_connection_t *c;
2158 u_char buf[256];
2159
2160 if (rev->timedout) { /* timeout expired */ }
2161
2162 c = rev->data;
2163
2164 while (rev->ready) {
2165 n = c->recv(c, buf, sizeof(buf));
2166
2167 if (n == NGX_AGAIN) {
2168 break;
2169 }
2170
2171 if (n == NGX_ERROR) { /* error */ }
2172
2173 /* process buf */
2174 }
2175
2176 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
2177 }
2178 </programlisting>
2179
2180 </section>
2181
2182
2183 <section name="Event loop" id="event_loop">
2184
2185 <para>
2186 All nginx processes which do I/O, have an event loop.
2187 The only type of process which does not have I/O, is nginx master process which
2188 spends most of its time in <literal>sigsuspend()</literal> call waiting for
2189 signals to arrive.
2190 Event loop is implemented in <literal>ngx_process_events_and_timers()</literal>
2191 function.
2192 This function is called repeatedly until the process exits.
2193 It has the following stages:
2194 </para>
2195
2196 <para>
2197 <list type="bullet">
2198
2199 <listitem>
2200 find nearest timeout by calling <literal>ngx_event_find_timer()</literal>.
2201 This function finds the leftmost timer tree node and returns the number of
2202 milliseconds until that node expires
2203 </listitem>
2204
2205 <listitem>
2206 process I/O events by calling a handler, specific to event notification
2207 mechanism, chosen by nginx configuration.
2208 This handler waits for at least one I/O event to happen, but no longer, than
2209 the nearest timeout.
2210 For each read or write event which has happened, the <literal>ready</literal>
2211 flag is set and its handler is called.
2212 For Linux, normally, the <literal>ngx_epoll_process_events()</literal> handler
2213 is used which calls <literal>epoll_wait()</literal> to wait for I/O events
2214 </listitem>
2215
2216 <listitem>
2217 expire timers by calling <literal>ngx_event_expire_timers()</literal>.
2218 The timer tree is iterated from the leftmost element to the right until a not
2219 yet expired timeout is found.
2220 For each expired node the <literal>timedout</literal> event flag is set,
2221 <literal>timer_set</literal> flag is reset, and the event handler is called
2222 </listitem>
2223
2224 <listitem>
2225 process posted events by calling <literal>ngx_event_process_posted()</literal>.
2226 The function repeatedly removes the first element from the posted events
2227 queue and calls its handler until the queue gets empty
2228 </listitem>
2229
2230 </list>
2231 </para>
2232
2233 <para>
2234 All nginx processes handle signals as well.
2235 Signal handlers only set global variables which are checked after the
2236 <literal>ngx_process_events_and_timers()</literal> call.
2237 </para>
2238
2239 </section>
2240
2241
2242 </section>
2243
2244
2245 <section name="Processes" id="processes">
2246
2247 <para>
2248 There are several types of processes in nginx.
2249 The type of current process is kept in the <literal>ngx_process</literal>
2250 global variable:
2251 </para>
2252
2253 <list type="bullet">
2254
2255 <listitem>
2256
2257 <para>
2258 <literal>NGX_PROCESS_MASTER</literal> - the master process runs the
2259 <literal>ngx_master_process_cycle()</literal> function.
2260 Master process does not have any I/O and responds only to signals.
2261 It reads configuration, creates cycles, starts and controls child processes
2262 </para>
2263
2264
2265 </listitem>
2266
2267 <listitem>
2268
2269 <para>
2270 <literal>NGX_PROCESS_WORKER</literal> - the worker process runs the
2271 <literal>ngx_worker_process_cycle()</literal> function.
2272 Worker processes are started by master and handle client connections.
2273 They also respond to signals and channel commands, sent from master
2274 </para>
2275
2276
2277 </listitem>
2278
2279 <listitem>
2280
2281 <para>
2282 <literal>NGX_PROCESS_SINGLE</literal> - single process is the only type
2283 of processes which exist in the <literal>master_process off</literal> mode.
2284 The cycle function for this process is
2285 <literal>ngx_single_process_cycle()</literal>.
2286 This process creates cycles and handles client connections
2287 </para>
2288
2289
2290 </listitem>
2291
2292 <listitem>
2293
2294 <para>
2295 <literal>NGX_PROCESS_HELPER</literal> - currently, there are two types of
2296 helper processes: cache manager and cache loader.
2297 Both of them share the same cycle function
2298 <literal>ngx_cache_manager_process_cycle()</literal>.
2299 </para>
2300
2301
2302 </listitem>
2303
2304 </list>
2305
2306 <para>
2307 All nginx processes handle the following signals:
2308 </para>
2309
2310 <list type="bullet">
2311
2312 <listitem>
2313
2314 <para>
2315 <literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal>) - graceful
2316 shutdown.
2317 Upon receiving this signal master process sends shutdown signal to all child
2318 processes.
2319 When no child processes are left, master destroys cycle pool and exits.
2320 A worker process which received this signal, closes all listening sockets and
2321 waits until timeout tree becomes empty, then destroys cycle pool and exits.
2322 A cache manager process exits right after receiving this signal.
2323 The variable <literal>ngx_quit</literal> is set to one after receiving this
2324 signal and immediately reset after being processed.
2325 The variable <literal>ngx_exiting</literal> is set to one when worker process
2326 is in shutdown state
2327 </para>
2328
2329
2330 </listitem>
2331
2332 <listitem>
2333
2334 <para>
2335 <literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal>) -
2336 terminate.
2337 Upon receiving this signal master process sends terminate signal to all child
2338 processes.
2339 If child processes do not exit in 1 second, they are killed with the
2340 <literal>SIGKILL</literal> signal.
2341 When no child processes are left, master process destroys cycle pool and exits.
2342 A worker or cache manager process which received this signal destroys cycle
2343 pool and exits.
2344 The variable <literal>ngx_terminate</literal> is set to one after receiving
2345 this signal
2346 </para>
2347
2348
2349 </listitem>
2350
2351 <listitem>
2352
2353 <para>
2354 <literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal>)
2355 - gracefully shut down worker processes
2356 </para>
2357
2358
2359 </listitem>
2360
2361 <listitem>
2362
2363 <para>
2364 <literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal>) -
2365 reconfigure.
2366 Upon receiving this signal master process creates a new cycle from
2367 configuration file.
2368 If the new cycle was created successfully, the old cycle is deleted and new
2369 child processes are started.
2370 Meanwhile, the old processes receive the shutdown signal.
2371 In single-process mode, nginx creates a new cycle as well, but keeps the old
2372 one until all clients, tied to the old cycle, are gone.
2373 Worker and helper processes ignore this signal
2374 </para>
2375
2376
2377 </listitem>
2378
2379 <listitem>
2380
2381 <para>
2382 <literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal>) - reopen
2383 files.
2384 Master process passes this signal to workers.
2385 Worker processes reopen all <literal>open_files</literal> from the cycle
2386 </para>
2387
2388
2389 </listitem>
2390
2391 <listitem>
2392
2393 <para>
2394 <literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal>) - change
2395 nginx binary.
2396 Master process starts a new nginx binary and passes there a list of all listen
2397 sockets.
2398 The list is passed in the environment variable <literal>"NGINX"</literal> in
2399 text format, where descriptor numbers separated with semicolons.
2400 A new nginx instance reads that variable and adds the sockets to its init
2401 cycle.
2402 Other processes ignore this signal
2403 </para>
2404
2405
2406 </listitem>
2407
2408 </list>
2409
2410 <para>
2411 While all nginx worker processes are able to receive and properly handle POSIX
2412 signals, master process normally does not pass any signals to workers and
2413 helpers with the standard <literal>kill()</literal> syscall.
2414 Instead, nginx uses inter-process channels which allow sending messages between
2415 all nginx processes.
2416 Currently, however, messages are only sent from master to its children.
2417 Those messages carry the same signals.
2418 The channels are socketpairs with their ends in different processes.
2419 </para>
2420
2421 <para>
2422 When running nginx binary, several values can be specified next to
2423 <literal>-s</literal> parameter.
2424 Those values are <literal>stop</literal>, <literal>quit</literal>,
2425 <literal>reopen</literal>, <literal>reload</literal>.
2426 They are converted to signals <literal>NGX_TERMINATE_SIGNAL</literal>,
2427 <literal>NGX_SHUTDOWN_SIGNAL</literal>, <literal>NGX_REOPEN_SIGNAL</literal>
2428 and <literal>NGX_RECONFIGURE_SIGNAL</literal> and sent to the nginx master
2429 process, whose pid is read from nginx pid file.
2430 </para>
2431
2432 </section>
2433
2434 </article>