開発ガイド

はじめに
     コード レイアウト
     インクルード ファイル
     数字
     共通 リターン コード
     エラーハンドリング
文字列
     概要
     フォーマット
     数値変換
     正規表現
コンテナ
     配列
     リスト
     キュー
     Red-Black tree
     ハッシュ
メモリ管理
     ヒープ
     プール
     共有メモリ
ログ
サイクル
バッファ
ネットワーク
     接続
イベント
     イベント
     I/O イベント
     タイマー イベント
     ポストされたイベント
     イベント ループ
プロセス
モジュール
     新しいモジュールの追加
     コア モジュール
     設定ディレクティブ
HTTP
     接続
     リクエスト
     設定
     フェーズ
     変数
     複雑な値
     応答
     応答ボディ
     ボディ フィルタ
     フィルタ モジュールのビルド
     バッファの再利用
     ロードバランシング

はじめに

コード レイアウト

インクルードファイル

各nginxファイルは以下の二つのファイルを含むところから始まらなければなりません:

#include <ngx_config.h>
#include <ngx_core.h>

それに加えて、HTTPコードは以下を含まなければなりません

#include <ngx_http.h>

メールコードは以下を含まなければなりません

#include <ngx_mail.h>

ストリームコードは以下を含まなければなりません

#include <ngx_stream.h>

整数

一般的な目的のために、nginxのコードはintptr_tuintptr_tについての型定義である二つ整数型 ngx_int_tngx_uint_tを使います。

共通リターンコード

nginxのほとんどの関数は以下のコードを返します:

エラーハンドリング

最後のシステムエラーコードを取得するために、ngx_errno マクロが利用可能です。POSIXプラットフォーム上のerrnoにマップされ、Windows内でGetLastError() コールにマップされます。最後のソケットエラー番号を取得するために、ngx_socket_errno マクロが利用可能です。POSIXシステム上のerrno にマップされ、Windows上でWSAGetLastError() にマップされます。パフォーマンス上の理由でngx_errno あるいは ngx_socket_errno の値は連続して1回以上アクセスされるべきではありません。必要であれば、複数回使うために、エラー値はローカル変数型 ngx_err_t に格納されるべきです。エラーを設定するために、ngx_set_errno(errno) および ngx_set_socket_errno(errno) マクロが利用可能です。

ngx_errno あるいは ngx_socket_errno の値はログ関数ngx_log_error()ngx_log_debugX() に渡すことができ、その場合、システムエラーテキストがログメッセージに追加されます。

ngx_errnoを使う例:

void
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}

文字列

概要

Cの文字列については、nginxのコードは符号無し文字型ポインタ u_char * を使います。

nginxの文字列型 ngx_str_t は以下のように定義されます:

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

len フィールドは文字列の長さを保持し、data は文字列のデータを保持します。ngx_str_tに保持されている文字列はlen バイトの後にnull終端子があるかも知れません。ほとんどの場合はありません。しかし、コードのある部分(例えば、設定をパースする場合)、ngx_str_t オブジェクトはnull終端だと知られていて、その知見は文字列の比較を単純化するために使われ、それらの文字列をシステムコールに渡すのを容易にします。

多くの文字列オペレータがnginx内で提供されます。それらはsrc/core/ngx_string.h内で定義されます。それらの幾つかは標準C関数をラップします:

幾つかのnginx固有の文字列関数:

幾つかの変換と比較関数:

フォーマット

多くのフォーマット関数がnginxによって提供されます。これらの関数はnginx固有の型をサポートします:

これらの関数によってサポートされるフォーマットオプションの完全なリストはsrc/core/ngx_string.cの中で見つけることができます。それらのうちの幾つか:

%O — off_t
%T — time_t
%z — size_t
%i — ngx_int_t
%p — void *
%V — ngx_str_t *
%s — u_char * (null-terminated)
%*s — size_t + u_char *

The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex.

例:

u_char     buf[NGX_INT_T_LEN];
size_t     len;
ngx_int_t  n;

/* set n here */

len = ngx_sprintf(buf, "%ui", n) — buf;

数値変換

数値変換の幾つかの関数はnginx内で実装されています:

正規表現

nginxでの正規表現インタフェースはPCRE ライブラリのラッパーです。対応するヘッダファイルは src/core/ngx_regex.hです。

文字列のマッチングのために正規表現を使うためには、まず、コンパイルされる必要があります。これは通常設定フェーズで行われます。PCREサポートは任意のため、インタフェースを使用している全てのコードは周りを取り巻くNGX_PCRE マクロによって保護されなければなりません:

#if (NGX_PCRE)
ngx_regex_t          *re;
ngx_regex_compile_t   rc;

u_char                errstr[NGX_MAX_CONF_ERRSTR];

ngx_str_t  value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'");

ngx_memzero(&rc, sizeof(ngx_regex_compile_t));

rc.pattern = value;
rc.pool = cf->pool;
rc.err.len = NGX_MAX_CONF_ERRSTR;
rc.err.data = errstr;
/* rc.options are passed as is to pcre_compile() */

if (ngx_regex_compile(&rc) != NGX_OK) {
    ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
    return NGX_CONF_ERROR;
}

re = rc.regex;
#endif

After successful compilation, ngx_regex_compile_t structure fields captures and named_captures are filled with count of all and named captures respectively found in the regular expression.

Later, the compiled regular expression may be used to match strings against it:

ngx_int_t  n;
int        captures[(1 + rc.captures) * 3];

ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");

n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
if (n >= 0) {
    /* string matches expression */

} else if (n == NGX_REGEX_NO_MATCHED) {
    /* no match was found */

} else {
    /* some error */
    ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
}

The arguments of ngx_regex_exec() are: the compiled regular expression re, string to match s, optional array of integers to hold found captures and its size. The captures array size must be a multiple of three, per requirements of the PCRE API. In the example, its size is calculated from a total number of captures plus one for the matched string itself.

Now, if there are matches, captures may be accessed:

u_char     *p;
size_t      size;
ngx_str_t   name, value;

/* all captures */
for (i = 0; i < n * 2; i += 2) {
    value.data = input.data + captures[i];
    value.len = captures[i + 1] — captures[i];
}

/* accessing named captures */

size = rc.name_size;
p = rc.names;

for (i = 0; i < rc.named_captures; i++, p += size) {

    /* capture name */
    name.data = &p[2];
    name.len = ngx_strlen(name.data);

    n = 2 * ((p[0] << 8) + p[1]);

    /* captured value */
    value.data = &input.data[captures[n]];
    value.len = captures[n + 1] — captures[n];
}

The ngx_regex_exec_array() function accepts the array of ngx_regex_elt_t elements (which are just compiled regular expressions with associated names), a string to match and a log. The function will apply expressions from the array to the string until the match is found or no more expressions are left. 合致した場合には返り値はNGX_OKで、そうでなければNGX_DECLINED、あるいはエラー時にはNGX_ERROR です。

コンテナ

配列

nginx配列型ngx_array_t は以下のように定義されます

typedef struct {
    void        *elts;
    ngx_uint_t   nelts;
    size_t       size;
    ngx_uint_t   nalloc;
    ngx_pool_t  *pool;
} ngx_array_t;

配列の要素はelts フィールドを使って利用可能です。要素の数はnelts フィールドに格納されています。size フィールドは1つの要素のサイズを保持し、配列を初期化する時に設定されます。

配列はngx_array_create(pool, n, size) 呼び出しを使ってプール内に生成することができます。既に割り当てられている配列オブジェクトは ngx_array_init(array, pool, n, size) 呼び出しを使って初期化することができます。

ngx_array_t  *a, b;

/* create an array of strings with preallocated memory for 10 elements */
a = ngx_array_create(pool, 10, sizeof(ngx_str_t));

/* initialize string array for 10 elements */
ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));

配列への要素の追加は以下の関数を使って行われます:

もし現在割り当てられているメモリが新しい要素に十分ではない場合、要素のための新しいメモリが割り当てられ、既存の要素がメモリにコピーされるでしょう。新しいメモリブロックは通常既存のものの2倍の大きさです。

s = ngx_array_push(a);
ss = ngx_array_push_n(&b, 3);

リスト

nginxでのリストは配列の系列で、潜在的に大量の項目を挿入できるように最適化されています。リストの型は以下のように定義されます:

typedef struct {
    ngx_list_part_t  *last;
    ngx_list_part_t   part;
    size_t            size;
    ngx_uint_t        nalloc;
    ngx_pool_t       *pool;
} ngx_list_t;

実施あの項目は、以下で定義されるリストの一部に格納されます:

typedef struct ngx_list_part_s  ngx_list_part_t;

struct ngx_list_part_s {
    void             *elts;
    ngx_uint_t        nelts;
    ngx_list_part_t  *next;
};

最初に、リストはngx_list_init(list, pool, n, size) の呼び出しで初期化されるか、ngx_list_create(pool, n, size)の呼び出しで生成されなければなりません。両方の関数とも1つの項目のサイズとリスト部分ごとの項目の数を受け取ります。ngx_list_push(list) 関数はリストに項目を追加するために使われます。以下の例で分かるように、直接リストのフィールドにアクセスすることで項目の繰り返しが行われます。

ngx_str_t        *v;
ngx_uint_t        i;
ngx_list_t       *list;
ngx_list_part_t  *part;

list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
if (list == NULL) { /* error */ }

/* add items to the list */

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "foo");

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "bar");

/* iterate over the list */

part = &list->part;
v = part->elts;

for (i = 0; /* void */; i++) {

    if (i >= part->nelts) {
        if (part->next == NULL) {
            break;
        }

        part = part->next;
        v = part->elts;
        i = 0;
    }

    ngx_do_smth(&v[i]);
}

nginxでのリストの主要な使い方はHTTP入力と出力ヘッダです。

リストは項目の削除をサポートしません。しかし、必要であれば、項目はリストから実際に削除すること無しに外すように内部的に印をつけることができます。例えば、ngx_table_elt_t として格納されているHTTP出力ヘッダは、ngx_table_elt_thash フィールドをゼロに設定することで外すことができます。ヘッダ上を繰り返す時に、そのような項目は明示的にスキップされます。

キュー

nginxでのキューは各ノードが以下のように定義されている二重にリンクされた出しゃばりのリストです:

typedef struct ngx_queue_s  ngx_queue_t;

struct ngx_queue_s {
    ngx_queue_t  *prev;
    ngx_queue_t  *next;
};

先頭のキューノードはどのようなデータともリンクしていません。使う前に、リストの先頭はngx_queue_init(q) 呼び出しで初期化される必要があります。キューは以下の操作をサポートします:

例:

typedef struct {
    ngx_str_t    value;
    ngx_queue_t  queue;
} ngx_foo_t;

ngx_foo_t    *f;
ngx_queue_t   values;

ngx_queue_init(&values);

f = ngx_palloc(pool, sizeof(ngx_foo_t));
if (f == NULL) { /* error */ }
ngx_str_set(&f->value, "foo");

ngx_queue_insert_tail(&values, f);

/* insert more nodes here */

for (q = ngx_queue_head(&values);
     q != ngx_queue_sentinel(&values);
     q = ngx_queue_next(q))
{
    f = ngx_queue_data(q, ngx_foo_t, queue);

    ngx_do_smth(&f->value);
}

赤黒木

src/core/ngx_rbtree.hヘッダファイルは赤黒木の効果的な実装への参照を提供します。

typedef struct {
    ngx_rbtree_t       rbtree;
    ngx_rbtree_node_t  sentinel;

    /* custom per-tree data here */
} my_tree_t;

typedef struct {
    ngx_rbtree_node_t  rbnode;

    /* custom per-node data */
    foo_t              val;
} my_node_t;

木を全体として扱うために、二つのノードが必要です: ルートと歩哨です。一般的にそれらは何らかの独自の構造に追加されます。従ってデータを葉がデータへのリンクあるいはデータを埋め込む木へ整理することができます。

木を初期化するには:

my_tree_t  root;

ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);

insert_value_function は木を行き来し、新しい値を正しい場所に挿入する責任を持つ関数です。例えば、ngx_str_rbtree_insert_value 関数はngx_str_t 型を扱うように設計されています。

void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
                                 ngx_rbtree_node_t *node,
                                 ngx_rbtree_node_t *sentinel)

引数は、挿入の付け根のノードへのポインタ、追加される新しく作成されたノード、および木の歩哨です。

行き来はとても率直なもので、以下の捜索機能パターンを使って実演することができます:

my_node_t *
my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
{
    ngx_int_t           rc;
    my_node_t          *n;
    ngx_rbtree_node_t  *node, *sentinel;

    node = rbtree->root;
    sentinel = rbtree->sentinel;

    while (node != sentinel) {

        n = (my_node_t *) node;

        if (hash != node->key) {
            node = (hash < node->key) ? node->left : node->right;
            continue;
        }

        rc = compare(val, node->val);

        if (rc < 0) {
            node = node->left;
            continue;
        }

        if (rc > 0) {
            node = node->right;
            continue;
        }

        return n;
    }

    return NULL;
}

compare() は、ゼロより少ない、等しい、あるいは大きいという値を返す伝統的な比較器です。検索を高速化し、大きいかも知れないユーザのオブジェクトの比較を避けるために、整数のハッシュフィールドが使われます。

ノードを木に追加するために、新しいノードを割り当て、それを初期化し、そしてngx_rbtree_insert()を呼びます:

    my_node_t          *my_node;
    ngx_rbtree_node_t  *node;

    my_node = ngx_palloc(...);
    init_custom_data(&my_node->val);

    node = &my_node->rbnode;
    node->key = create_key(my_node->val);

    ngx_rbtree_insert(&root->rbtree, node);

ノードを削除するには:

ngx_rbtree_delete(&root->rbtree, node);

ハッシュ

ハッシュテーブル関数は src/core/ngx_hash.h で定義されています。正確、およびワイルドカードの合致がサポートされます。後者は特別なセットアップを必要とし、以下の別の章で説明されます。

nginxはハッシュを任意でビルドすることができるため、ハッシュを初期化するには、前もって要素の数を知る必要があります。設定するために必要な二つのパラメータは max_sizebucket_size です。これらのセットアップの詳細は、別のドキュメントの中で提供されます。通常、これらの二つのパラメータはユーザによって設定されます:ハッシュの初期化設定はngx_hash_init_t 型として格納され、ハッシュ自身は ngx_hash_tです:

ngx_hash_t       foo_hash;
ngx_hash_init_t  hash;

hash.hash = &foo_hash;
hash.key = ngx_hash_key;
hash.max_size = 512;
hash.bucket_size = ngx_align(64, ngx_cacheline_size);
hash.name = "foo_hash";
hash.pool = cf->pool;
hash.temp_pool = cf->temp_pool;

キー は文字列からハッシュの整数キーを生成する関数へのポインタです。二つの一般的な関数が提供されています:ngx_hash_key(data, len)ngx_hash_key_lc(data, len)。後者は文字列を小文字に変換します。従って渡される文字列が書き込み可能である必要があります。そうでない場合は、配列キーを初期化するNGX_HASH_READONLY_KEY フラグが関数に渡されるかも知れません (以下を見てください)。

ハッシュのキーはngx_hash_keys_arrays_tに格納され、ngx_hash_keys_array_init(arr, type)を使って初期化されます:

ngx_hash_keys_arrays_t  foo_keys;

foo_keys.pool = cf->pool;
foo_keys.temp_pool = cf->temp_pool;

ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);

二つ目のパラメータはNGX_HASH_SMALL あるいは NGX_HASH_LARGE のどちらかが可能で、ハッシュのための予め割り当てられるリソースの量を制御します。ハッシュが多数の要素を含むことが期待される場合、NGX_HASH_LARGEを使ってください。

ngx_hash_add_key(keys_array, key, value, flags)関数はキーをハッシュキー配列に挿入するために使われます;

ngx_str_t k1 = ngx_string("key1");
ngx_str_t k2 = ngx_string("key2");

ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);

ここで、ハッシュテーブルはngx_hash_init(hinit, key_names, nelts)の呼び出しを使って構築されるかも知れません:

ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);

max_size あるいは bucket_size パラメータが十分に大きくない場合は、これは失敗するかも知れません。ハッシュが構築される時、ngx_hash_find(hash, key, name, len) 関数は要素を調べるために使われるかも知れません:

my_data_t   *data;
ngx_uint_t   key;

key = ngx_hash_key(k1.data, k1.len);

data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
if (data == NULL) {
    /* key not found */
}

ワイルドカード マッチング

ワイルドカードを使って動作するハッシュを生成するには、ngx_hash_combined_t 型が使われます。それは、上で説明されるハッシュ型を含み、二つの追加のキー配列を持ちます: dns_wc_headdns_wc_tail。基本的なプロパティの初期化は通常のハッシュと同じように行われます:

ngx_hash_init_t      hash
ngx_hash_combined_t  foo_hash;

hash.hash = &foo_hash.hash;
hash.key = ...;

NGX_HASH_WILDCARD_KEY フラグを使ってワイルドカードキーを追加することが可能です:

/* k1 = ".example.org"; */
/* k2 = "foo.*";        */
ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);

関数はワイルドカードを理解し、キーを対応する配列に追加します。ワイルドカードの構文と合致アルゴリズムの説明については、map モジュールのドキュメントを参照してください。

追加されたキーの内容に依存して、三つのキー配列を初期化する必要があるかも知れません: 1つは(上で説明された)完全な合致のため、2つは文字列の始まりあるいは終わりから開始する合致のためです。

if (foo_keys.dns_wc_head.nelts) {

    ngx_qsort(foo_keys.dns_wc_head.elts,
              (size_t) foo_keys.dns_wc_head.nelts,
              sizeof(ngx_hash_key_t),
              cmp_dns_wildcards);

    hash.hash = NULL;
    hash.temp_pool = pool;

    if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
                               foo_keys.dns_wc_head.nelts)
        != NGX_OK)
    {
        return NGX_ERROR;
    }

    foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
}

キー配列はソートされる必要があり、初期化の結果は結合されたハッシュに追加されなければなりません。dns_wc_tail 配列の初期化は同じように行われます。

結合されたハッシュ内での照合はngx_hash_find_combined(chash, key, name, len)によって扱われます:

/* key = "bar.example.org"; — will match ".example.org" */
/* key = "foo.example.com"; — will match "foo.*"        */

hkey = ngx_hash_key(key.data, key.len);
res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);

メモリ管理

ヒープ

システムヒープからメモリを割り当てるために、以下の関数がnginxによって提供されています:

プール

ほとんどのnginxの割り当てはプール内で行われます。nginxのプールで割り当てられたメモリはプールが破壊された時に自動的に開放されます。これにより割り当てのパフォーマンスが良くなり、メモリの制御が簡単になります。

プールはメモリの連続するブロックの中でオブジェクトを内部的に割り当てます。ブロックが埋まると、新しいブロックが割り当てられ、プールメモリブロックリストへ追加されます。ブロックに収まらない大きな割り当てが要求された場合、そのような割り当てはシステムのアロケータに転送され、更なる割り当ての解除のためにプール内に返されたポインタが格納されます。

Nginxのプールは型ngx_pool_tを持ちます。以下の操作がサポートされます:

u_char      *p;
ngx_str_t   *s;
ngx_pool_t  *pool;

pool = ngx_create_pool(1024, log);
if (pool == NULL) { /* error */ }

s = ngx_palloc(pool, sizeof(ngx_str_t));
if (s == NULL) { /* error */ }
ngx_str_set(s, "foo");

p = ngx_pnalloc(pool, 3);
if (p == NULL) { /* error */ }
ngx_memcpy(p, "foo", 3);

nginxではチェイン リンク ngx_chain_t が積極的に使われるため、nginxのプールはそれらを再利用する方法を提供します。ngx_pool_tchain フィールドは再利用のために以前割り当てられたリンクのリストを準備し続けます。プール内での効率的なチェインリンクの割り当てのために、関数ngx_alloc_chain_link(pool) が使われるべきです。This function looks up a free chain link in the pool list and only if it's empty allocates a new one. リンクを解放するにはngx_free_chain(pool, cl)が呼ばれるべきです。

クリーンナップ ハンドラはプール内に登録することができます。クリーンナップ ハンドラはプールが破壊される時に呼ばれる引数を持つコールバックです。プールは通常特定の(HTTPリクエスト)のようなnginxオブジェクトと紐付けられ、オブジェクトの生存期間の最後にはオブジェクト自身を解放しながら破壊されます。Registering a pool cleanup is a convenient way to release resources, close file descriptors or make final adjustments to shared data, associated with the main object.

A pool cleanup is registered by calling ngx_pool_cleanup_add(pool, size) which returns ngx_pool_cleanup_t pointer to be filled by the caller. size引数はクリーンナップ ハンドラのためにコンテキストを割り当てることができます。

ngx_pool_cleanup_t  *cln;

cln = ngx_pool_cleanup_add(pool, 0);
if (cln == NULL) { /* error */ }

cln->handler = ngx_my_cleanup;
cln->data = "foo";

...

static void
ngx_my_cleanup(void *data)
{
    u_char  *msg = data;

    ngx_do_smth(msg);
}

共有メモリ

共有メモリはプロセス間での共通データを共有するためにnginxによって使われます。関数 ngx_shared_memory_add(cf, name, size, tag) はサイクルに新しい共有メモリ エントリ ngx_shm_zone_t を追加します。関数はゾーンのnamesize を受け取ります。各共有ゾーンはユニークな名前を持たなければなりません。もし指定された名前を持つ共有ゾーン エントリが存在する場合、タグの値も一致すれば古いゾーン エントリは再利用されます。一致しないタグはエラーと見なされます。通常、モジュール構造のアドレスがタグとして渡され、1つのnginxモジュール内で名前によって共有ゾーンを再利用することができます。

共有メモリ エントリ構造 ngx_shm_zone_t は以下のフィールドを持ちます:

共有ゾーン エントリは設定がパースされた後でngx_init_cycle()内の実際のメモリにマップされます。POSIXシステム上では、mmap() syscall が共有匿名マッピングを生成するために使われます。Windows上では、CreateFileMapping()/MapViewOfFileEx() ペアが使われます。

共有メモリ内で割り当てるために、nginxはスラブ プール ngx_slab_pool_t を提供します。各nginx共有ゾーンの中で、スラブ プールはそのゾーン内でメモリを割り当てるために自動的に生成されます。プールは共有ゾーンの最初に位置していて、表現(ngx_slab_pool_t *) shm_zone->shm.addr によってアクセスすることができます。共有ゾーンでの割り当ては ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size)関数のうちの一つの呼び出しによって行われます。メモリは ngx_slab_free(pool, p)の呼び出しによって解放されます。

スラブ プールは全ての共有ゾーンをページに分割します。各ページは同じサイズのオブジェクトを割り当てるために使われます。8以上の二乗のサイズが考慮されます。他のサイズはそれらの値のうちの一つに丸められます。For each page, a bitmask is kept, showing which blocks within that page are in use and which are free for allocation. 半分のページ(通常 2048バイト)より大きい場合、ページ全体まで割り当てが行われます。

同時アクセスから共有メモリ内のデータを守るためには、ngx_slab_pool_tmutexフィールド内でmutexが利用可能です。メモリを割り当ておよび開放する間、スラブによってmutexが使われます。しかし、それは共有ゾーン内で割り当てられてる他のユーザデータ構造を保護するために使うことができます。ngx_shmtx_lock(&shpool->mutex)を呼び出すことでロッキングが行われ、ngx_shmtx_unlock(&shpool->mutex)を呼び出すことでアンロッキングが行われます。

ngx_str_t        name;
ngx_foo_ctx_t   *ctx;
ngx_shm_zone_t  *shm_zone;

ngx_str_set(&name, "foo");

/* allocate shared zone context */
ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
if (ctx == NULL) {
    /* error */
}

/* add an entry for 65k shared zone */
shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
if (shm_zone == NULL) {
    /* error */
}

/* register init callback and context */
shm_zone->init = ngx_foo_init_zone;
shm_zone->data = ctx;


...


static ngx_int_t
ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
{
    ngx_foo_ctx_t  *octx = data;

    size_t            len;
    ngx_foo_ctx_t    *ctx;
    ngx_slab_pool_t  *shpool;

    value = shm_zone->data;

    if (octx) {
        /* reusing a shared zone from old cycle */
        ctx->value = octx->value;
        return NGX_OK;
    }

    shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;

    if (shm_zone->shm.exists) {
        /* initialize shared zone context in Windows nginx worker */
        ctx->value = shpool->data;
        return NGX_OK;
    }

    /* initialize shared zone */

    ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
    if (ctx->value == NULL) {
        return NGX_ERROR;
    }

    shpool->data = ctx->value;

    return NGX_OK;
}

ログ

nginxのコードを記録するには、ngx_log_t オブジェクトを使います。Nginxのロガーは出力の幾つかのタイプをサポートします:

ロガーインスタンスは実際にはお互いにnext フィールドでリンクされたロガーのチェーンかも知れません。各メッセージはチェーン内で全てのロガーに記録されます。

各ロガーはログに書き込まれるメッセージを制限するエラーレベルを持ちます。以下のエラーレベルがnginxでサポートされます:

デバッグのログのために、デバッグマスクもチェックされます。以下のデバッグマスクが存在します:

通常、ロガーは既存のnginxコードによってerror_log ディレクティブから生成され、サイクル、設定、クライアント接続および他のオブジェクトのほとんど全ての処理のステージで利用可能です。

Nginx は以下のログ マクロを提供します:

ログメッセージはスタック上のサイズNGX_MAX_ERROR_STR (現在のところ 2048 バイト)のバッファ内で整形されます。メッセージはエラーレベル、プロセスID,接続id (log->connectionに格納されています)およびシステムエラー テキストが前に付きます。非デバッグメッセージについては、もっと特定の情報がログメッセージに付くようにlog->handlerが呼ばれます。HTTP モジュールは、クライアントとサーバアドレス、現在のアクション(log->actionに格納されています)、クライアント リクエスト ライン、サーバ名などを記録するためにログ ハンドラとしてngx_http_log_error()関数を設定します。

例:

/* specify what is currently done */
log->action = "sending mp4 to client”;

/* error and debug log */
ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
              closed connection”);

ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
               "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);

Logging result:

2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000

サイクル

サイクルオブジェクトは特定の設定から生成されるnginxの実行時コンテキストを保持します。サイクルの型はngx_cycle_tです。設定がリロードされる時、新しいサイクルがnginx設定の新しいバージョンから生成されます。古いサイクルは新しいものがうまく生成された後で通常削除されます。現在のところ、活動中のサイクルはngx_cycle グローバル変数に格納され、新しくスタートしたnginxワーカーによって継承されます。

サイクルは関数 ngx_init_cycle() によって生成されます。関数は古いサイクルを引数として取ります。それは設定ファイルの場所を特定するために使われ、nginxをスムーズに実行し続けるために古いサイクルからできる限り多くのリソースを継承します。nginxが開始した時に、"init cycle"と呼ばれる偽物のサイクルが生成され、その後設定から作られた通常のサイクルによって置き換えられます。

サイクルの幾つかのメンバー:

バッファ

入力/出力オペレーションのために、nginxはバッファ型 ngx_buf_tを提供します。通常、それは宛先に書き込まれるためのデータを保持するためか、ソースから読み込むために使われます。バッファはメモリ内およびファイル内でデータを参照することができます。技術的には、バッファが同時に二つを参照することができます。バッファのためのメモリは個々に割り当てられ、バッファ構造 ngx_buf_t には関係しません。

構造 ngx_buf_t は以下のフィールドを持ちます:

入力および出力のために、バッファはチェーンでリンクされます。チェーンはチェーンリンクngx_chain_tの順列で、以下のように定義されます:

typedef struct ngx_chain_s  ngx_chain_t;

struct ngx_chain_s {
    ngx_buf_t    *buf;
    ngx_chain_t  *next;
};

各チェーンリンクはバッファへの参照と次のチェーンリンクへの参照を保持します。

バッファとチェーンの使用例:

ngx_chain_t *
ngx_get_my_chain(ngx_pool_t *pool)
{
    ngx_buf_t    *b;
    ngx_chain_t  *out, *cl, **ll;

    /* first buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_calloc_buf(pool);
    if (b == NULL) { /* error */ }

    b->start = (u_char *) "foo";
    b->pos = b->start;
    b->end = b->start + 3;
    b->last = b->end;
    b->memory = 1; /* read-only memory */

    cl->buf = b;
    out = cl;
    ll = &cl->next;

    /* second buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_create_temp_buf(pool, 3);
    if (b == NULL) { /* error */ }

    b->last = ngx_cpymem(b->last, "foo", 3);

    cl->buf = b;
    cl->next = NULL;
    *ll = cl;

    return out;
}

ネットワーク

接続

接続型 ngx_connection_t はソケットディスクリプタのラッパーです。構造のフィールドの幾つかは次のようなものです:

nginxの接続は透過的にSSL層をカプセル化します。この場合、接続ssl フィールドはngx_ssl_connection_t 構造へのポインタを保持し、SSL_CTXSSLを含む接続のための全てのSSLに関係するデータを持ち続けます。ハンドラ recv, send, recv_chain, send_chain はSSL関数へも設定されます。

nginxのワーカーあたりの接続の数はworker_connectionsの値によって制限されます。全ての接続の構造は、ワーカーが開始する時にあらかじめ作成され、サイクルオブジェクトのconnectionsフィールドの中に格納されます。接続の構造に手を伸ばすには、ngx_get_connection(s, log)関数が使われます。関数は接続構造の中でラップされる必要がある複数の ソケットディスクリプタを受け取ります。

ワーカーあたりの接続の数が制限されるため、nginxは現在使われている接続を横取りする方法を提供します。接続の再利用を有効あるいは無効にするために、関数ngx_reusable_connection(c, reusable) が呼ばれます。ngx_reusable_connection(c, 1)の呼び出しは接続構造のreuse フラグを設定し、その接続をサイクルのreusable_connections_queue に挿入します。ngx_get_connection()はサイクルのfree_connections リストの中に利用可能な接続が無いと分かるといつでも特定の数の再利用可能な接続lを解放するためにngx_drain_connections()を呼びます。For each such connection, the close flag is set and its read handler is called which is supposed to free the connection by calling ngx_close_connection(c) and make it available for reuse. 接続が再利用可能な時に状態を抜けるためにngx_reusable_connection(c, 0)が呼ばれます。nginxでの再利用可能な接続の例は、クライアントから何らかのデータを受け取るまで再利用可能だとマークされているHTTPクライアントの接続です。

イベント

イベント

nginxでのイベントオブジェクトngx_event_t は特定のイベントが起きていることを伝える方法を提供します。

ngx_event_tのフィールドの幾つかは次のようなものです:

I/O イベント

ngx_get_connection() 呼び出しによって受け取られた各接続は、それに付随する二つのイベントを持ちます: c->readc->write。これらのイベントは読み込みあるいは書き込みの準備ができたソケットについての通知を受け取るために使われます。全てのそのようなイベントはEdge-Triggeredモードで操作されます。ソケットの状態の変更時にそれらは通知を引き起こすことを意味します。例えば、ソケット上の部分的な読み込みの実施は、ソケットにもっと多くのデータが到着するまでnginxに繰り返しの読み込み通知を配送しないでしょう。背後で動くI/O通知機構が本質的に Level-Triggered (poll, select など)であった場合でも、nginxは通知を Edge-Triggered に変えるでしょう。To make nginx event notifications consistent across all notifications systems on different platforms, it's required, that the functions ngx_handle_read_event(rev, flags) and ngx_handle_write_event(wev, lowat) are called after handling an I/O socket notification or calling any I/O functions on that socket. 通常、これらの関数は各読み込みあるいは書き込みイベントハンドラの最後に一度だけ呼ばれます。

タイマー イベント

イベントはタイムアウトの期限切れを通知するために設定することができます。関数 ngx_add_timer(ev, timer) はイベントのタイムアウトを設定し、ngx_del_timer(ev) は以前に設定されたタイムアウトを削除します。現在のところ全ての既存のイベントに設定されたタイムアウトはグローバルタイムアウト 赤黒木 ngx_event_timer_rbtree に保持されます。木でのキーは型ngx_msec_tを持ち、イベントが期限切れになる1970年1月1日 (modulus ngx_msec_t の最大値)からのミリ秒の時間です。木構造は高速な挿入と削除操作を提供し、もっとも近いタイムアウトへのアクセスを提供します。The latter is used by nginx to find out for how long to wait for I/O events and for expiring timeout events afterwards.

ポストされたイベント

イベントがポストされるかも知れません。ハンドルが現在のイベントループの繰り返しの中でどこかの時点の後で呼ばれるかも知れないという意味です。イベントのポストはコードを単純化しスタックオーバーフローを避けるための良い練習です。ポストされたイベントはポストキューの中に保持されます。マクロ ngx_post_event(ev, q) はイベント ev をポストキューqにポストします。マクロ ngx_delete_posted_event(ev) はイベント ev を現在ポストされたどのようなキューからでも削除します。通常、イベントは ngx_posted_events キューにポストされます。このキューはイベントループの中で、全てのI/Oおよびタイマーイベントがすでに処理された後で処理されます。関数 ngx_event_process_posted() はイベントキューを処理するために呼ばれます。この関数はキューが空になるまでイベントハンドラを呼びます。このことは、ポストされたイベントハンドラは現在のイベントループの繰り返しの中で処理されるされるようにもっと多くのイベントをポストすることができることを意味します。

例:

void
ngx_my_connection_read(ngx_connection_t *c)
{
    ngx_event_t  *rev;

    rev = c->read;

    ngx_add_timer(rev, 1000);

    rev->handler = ngx_my_read_handler;

    ngx_my_read(rev);
}


void
ngx_my_read_handler(ngx_event_t *rev)
{
    ssize_t            n;
    ngx_connection_t  *c;
    u_char             buf[256];

    if (rev->timedout) { /* timeout expired */ }

    c = rev->data;

    while (rev->ready) {
        n = c->recv(c, buf, sizeof(buf));

        if (n == NGX_AGAIN) {
            break;
        }

        if (n == NGX_ERROR) { /* error */ }

        /* process buf */
    }

    if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
}

イベントループ

I/Oを行う全てのnginxプロセスはイベントループを持ちます。I/Oを持たないプロセスの唯一の型は、シグナルがやってくるのを待つsigsuspend()呼び出しの中でほとんどの時間を過ごすnginxのマスタープロセスです。イベントループはngx_process_events_and_timers() 関数の中で実装されています。この関数はプロセスが終了するまで繰り返し呼ばれます。以下のステージを持ちます:

全てのnginxプロセスもシグナルを処理します。シグナルハンドラは、ngx_process_events_and_timers()呼び出しの後でチェックされるグローバル変数にのみ設定します。

プロセス

nginxには処理の幾つかのタイプがあります:現在のプロセスのタイプはngx_process グローバル変数の中に保持されます:

全てのnginxプロセスは以下のシグナルを処理します:

全てのnginxワーカープロセスはPOSIXのシグナルを受け取り適切に処理することができますが、マスタープロセスは通常どのようなシグナルも標準のkill() syscollを持つワーカーやヘルパーに渡しません。代わりに、nginxは全てのnginxプロセス間でメッセージを送信することができる内部プロセスチャネルを使います。しかし、現在のところ、メッセージはマスターからその子プロセスにのみ送信されます。これらのメッセージは同じシグナルを伝搬することができます。チャネルは異なるプロセスに終端を持つソケットのペアです。

実行中のnginxバイナリの場合、-s パラメータの次に幾つかの値を指定することができます。これらの値は、stop, quit, reopen, reloadです。それらはシグナルNGX_TERMINATE_SIGNAL, NGX_SHUTDOWN_SIGNAL, NGX_REOPEN_SIGNAL および NGX_RECONFIGURE_SIGNAL に変換され、nginx pidファイルからpidを読み込んでnginxマスタープロセスに送信されます。

モジュール

新しいモジュールの追加

スタンドアローンのnginxモジュールは少なくとも以下の2つのファイルを含む別個のディレクトリ内にあります: config とモジュールのソースと一緒のファイル最初のファイルはnginxがモジュールを統合するために必要な全ての情報を含みます。例えば:

ngx_module_type=CORE
ngx_module_name=ngx_foo_module
ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"

. auto/module

ngx_addon_name=$ngx_module_name

ファイルはPOSIXのシェルスクリプトで以下の変数を設定(あるいはアクセス)することができます:

静的なコンパイルについては--add-module=/path/to/module を、動的なコンパイルについては--add-dynamic-module=/path/to/moduleを使って、設定スクリプトをによってnginxにモジュールを追加することができます。

コアモジュール

モジュールはnginxのブロックを構築し、その機能のほとんどはモジュールとして実装されます。モジュールのソースファイルは以下のように定義されるグローバル変数ngx_module_t 型を含まなければなりません:

struct ngx_module_s {

    /* private part is omitted */

    void                 *ctx;
    ngx_command_t        *commands;
    ngx_uint_t            type;

    ngx_int_t           (*init_master)(ngx_log_t *log);

    ngx_int_t           (*init_module)(ngx_cycle_t *cycle);

    ngx_int_t           (*init_process)(ngx_cycle_t *cycle);
    ngx_int_t           (*init_thread)(ngx_cycle_t *cycle);
    void                (*exit_thread)(ngx_cycle_t *cycle);
    void                (*exit_process)(ngx_cycle_t *cycle);

    void                (*exit_master)(ngx_cycle_t *cycle);

    /* stubs for future extensions are omitted */
};

省略されたprivate部分はモジュールのバージョン、シグネチャーを含み、事前定義されたマクロNGX_MODULE_V1を使って埋められます。

各モジュールはprivateデータをctx フィールドに保持し、特定の設定ディレクティブを理解し、commands 配列の中で指定され、nginxのライフサイクルの特定のステージで起動されるかも知れません。モジュールのライフサイクルは以下のイベントから成ります:

設定の再読み込みが要求された場合には、init_module ハンドラがマスタープロセス内で複数回呼ばれるかも知れません。

init_master, init_thread および exit_thread ハンドラは今のところ実装されていません; nginxでのスレッドは独自のAPIによって補助的なI/O機能としてのみ使われており、init_master ハンドラは必要無いように思われます。

モジュールのtype 型はctx フィールド内に何が保持されるかを正確に定義します。モジュールの型には幾つかあります:

NGX_CORE_MODULE は最も基本的で、従って最も一般的で最も低レベルのモジュールの型です。他のモジュール型はその上に実装され、イベントあるいはhttpリクエストの処理のような対応する問題ドメインを扱うための便利な方法を提供します。

コアモジュールの例は ngx_core_module, ngx_errlog_module, ngx_regex_module, ngx_thread_pool_module, ngx_openssl_module モジュール、そしてもちろん http, stream, mail および イベントモジュール自身です。コアモジュールのコンテキストは以下のように定義されます:

typedef struct {
    ngx_str_t             name;
    void               *(*create_conf)(ngx_cycle_t *cycle);
    char               *(*init_conf)(ngx_cycle_t *cycle, void *conf);
} ngx_core_module_t;

ここで、name は便利なようにモジュール名を持つ文字列で、create_confinit_conf はそれぞれモジュールの設定を生成および初期化する関数へのポインタです。コアモジュールについては、nginxは新しい設定をパースする前にcreate_conf を呼び、全ての設定のパースが成功した後で init_conf を呼ぶでしょう。代表的な create_conf 関数は設定のためのメモリを割り当て、デフォルトの値を設定します。init_conf は良く知られた設定を扱い、従って正常性チェックと徹底的な初期化をおこなうかも知れません。

例えば、極度に単純化されたngx_foo_moduleは以下のように見えるかも知れません:

/*
 * Copyright (C) Author.
 */


#include <ngx_config.h>
#include <ngx_core.h>


typedef struct {
    ngx_flag_t  enable;
} ngx_foo_conf_t;


static void *ngx_foo_create_conf(ngx_cycle_t *cycle);
static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf);

static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_enable_post = { ngx_foo_enable };


static ngx_command_t  ngx_foo_commands[] = {

    { ngx_string("foo_enabled"),
      NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG,
      ngx_conf_set_flag_slot,
      0,
      offsetof(ngx_foo_conf_t, enable),
      &ngx_foo_enable_post },

      ngx_null_command
};


static ngx_core_module_t  ngx_foo_module_ctx = {
    ngx_string("foo"),
    ngx_foo_create_conf,
    ngx_foo_init_conf
};


ngx_module_t  ngx_foo_module = {
    NGX_MODULE_V1,
    &ngx_foo_module_ctx,                   /* module context */
    ngx_foo_commands,                      /* module directives */
    NGX_CORE_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static void *
ngx_foo_create_conf(ngx_cycle_t *cycle)
{
    ngx_foo_conf_t  *fcf;

    fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
    if (fcf == NULL) {
        return NULL;
    }

    fcf->enable = NGX_CONF_UNSET;

    return fcf;
}


static char *
ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf)
{
    ngx_foo_conf_t *fcf = conf;

    ngx_conf_init_value(fcf->enable, 0);

    return NGX_CONF_OK;
}


static char *
ngx_foo_enable(ngx_conf_t *cf, void *post, void *data)
{
    ngx_flag_t  *fp = data;

    if (*fp == 0) {
        return NGX_CONF_OK;
    }

    ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");

    return NGX_CONF_OK;
}

設定ディレクティブ

ngx_command_t は1つの設定ディレクティブを記述します。設定をサポートする各モジュールは、引数をどうやって処理するか、どのハンドラを呼ぶかを記述する、そのような仕様の配列を提供します:

struct ngx_command_s {
    ngx_str_t             name;
    ngx_uint_t            type;
    char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
    ngx_uint_t            conf;
    ngx_uint_t            offset;
    void                 *post;
};

配列は特別な値 “ngx_null_command” を使って終わらなければなりません。The name is the literal name of a directive, as it appears in configuration file, for example “worker_processes” or “listen”. type は対応するフラグを使った、引数の数、コマンド型、および他のプロパティを制御するビット列です。引数のフラグ:

ディレクティブ型:

ディレクティブのコンテキストは設定のどこに現れるか、そして対応する値を格納するためにモジュールコンテキストにアクセスする方法を定義します。

設定パーサは間違ったディレクティブの場合にエラーを投げるためにこのフラグを使用し、適切な設定ポインタによって提供されるディレクティブハンドラを呼び出します。そしやって、異なるlocation内の同じディレクティブが個々の場所でそれらの値を格納できるようにします。

set フィールドはディレクティブを処理するハンドラを定義し、パースされた値を対応する設定に格納します。Nginxは共通の変換を行う便利な関数のセットを提供します:

conf フィールドはどのコンテキストがディレクティブの値を格納するために使われるかを定義します。コンテキストが使われない場合はゼロです。1つのコアモジュールだけがコンテキスト無しの設定を使用し、NGX_DIRECT_CONF フラグを設定します。実際には、httpあるいはstreamのようなモジュールはpre-serverあるいはpre-location、あるいはもっと正確に“if” ディレクティブあるいは何らかの制限の中に適用することができるようなもっと洗練された設定を必要とします。このモジュール内では、設定構造はもっと複雑です。それらが設定をどう管理するかについて理解するために対応するモジュールの説明を参照してください。

offset はこの特定のディレクティブの値を保持するモジュール設定構造内のフィールドのオフセットを定義します。代表的な使い方はoffsetof() マクロを使うことです。

post は二つの部分からなるフィールドです: メインのハンドラが終了した後で呼ばれるか、あるいは追加のデータをメインのハンドラに渡すために使われるかも知れません。最初の場合には、ngx_conf_post_t 構造はハンドラへのポインタを使って初期化される必要があります。例えば:

static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_post = { ngx_do_foo };

post の引数はngx_conf_post_t オブジェクト自身で、data は値へのポインタで、適切な型を持つメインのハンドラによって引数から変換されます。

HTTP

接続

各クライアントのHTTP接続は以下のステージを通過します:

リクエスト

各クライアントのHTTPリクエストに関して、ngx_http_request_t オブジェクトが生成されます。このオブジェクトの幾つかのフィールド:

設定

各HTTPモジュールは3つの種類の設定を持つかも知れません:

設定構造は関数の呼び出しによってnginx設定ステージで生成されます。これらの構造を割り当て、初期化し、そして合併します。以下の例は1つのモジュールの location 設定を生成する方法を示します。設定は1つのunsigned integer型のfoo を持ちます。

typedef struct {
    ngx_uint_t  foo;
} ngx_http_foo_loc_conf_t;


static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    ngx_http_foo_create_loc_conf,          /* create location configuration */
    ngx_http_foo_merge_loc_conf            /* merge location configuration */
};


static void *
ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_foo_loc_conf_t  *conf;

    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
    if (conf == NULL) {
        return NULL;
    }

    conf->foo = NGX_CONF_UNSET_UINT;

    return conf;
}


static char *
ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_foo_loc_conf_t *prev = parent;
    ngx_http_foo_loc_conf_t *conf = child;

    ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
}

例にあるように、ngx_http_foo_create_loc_conf() 関数は新しい設定構造を生成し、ngx_http_foo_merge_loc_conf() は設定を高レベルからの他の設定とマージします。実際、serverとlocation設定はserverとlocationレベルだけに存在するだけでなく、その上の全ての設定のためにも生成されます。特に、server設定はmainレベルに生成され、location設定はmain, server および location レベルのために生成されます。これらの設定によりnginx設定ファイルの任意のレベルでserverおよびlocation固有の設定を指定することができます。結果的に設定がマージされます。マージの間で消える設定と無視される設定を示すために、nginxはNGX_CONF_UNSETおよびNGX_CONF_UNSET_UINTのような多くのマクロを提供します。ngx_conf_merge_value() およびngx_conf_merge_uint_value()のような標準のnginxマージ マクロ は、明示的な値で設定がされない場合に設定をマージしデフォルト値を設定する簡単な方法を提供します。異なる型のための完全なマクロのリストについては、src/core/ngx_conf_file.hを見てください。

設定時の任意のHTTPモジュールの設定にアクセスするには、以下のマクロが利用可能です。それらは最初の引数としてngx_conf_t の参照を受け取ります。

以下の例は標準nginxコアモジュール ngx_http_core_module のlocation設定へのポインタを取得し、構造の handler フィールド内に保持されたlocationコンテントハンドラを変更します。

static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);


static ngx_command_t  ngx_http_foo_commands[] = {

    { ngx_string("foo"),
      NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
      ngx_http_foo,
      0,
      0,
      NULL },

      ngx_null_command
};


static char *
ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;

    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_bar_handler;

    return NGX_CONF_OK;
}

実行時には、以下のマクロがHTTPモジュールの設定を取得するために利用可能です。

これらのマクロはHTTPリクエスト ngx_http_request_t へのリファレンスを受け取ります。リクエストのメインの設定は変更されません。server 設定は、リクエストのためのバーチャルサーバを選択した後で、デフォルトのものから変わるかもしれません。リクエストのlocation設定は、rewriteあるいは内部リダイレクトの結果として、複数回変更されるかも知れません。以下の例は実行時にHTTP設定へアクセスする方法を示します。

static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_http_foo_loc_conf_t  *flcf;

    flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);

    ...
}

フェーズ

各HTTPリクエストはHTTPフェーズのリストを通過します。各フェーズは特定の処理が得意です。ほとんどのフェーズはハンドラを差し込むことができます。フェーズハンドラは、いったんリクエストがフェーズに到達すると連続して呼ばれます。多くの標準のnginxモジュールが特定のリクエストの処理ステージで呼ばれる方法としてフェーズハンドラを差し込みます。以下はnginx HTTPフェーズのリストです。

以下はアクセス前のフェーズハンドラの例です。

static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    ngx_http_foo_init,                     /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_str_t  *ua;

    ua = r->headers_in->user_agent;

    if (ua == NULL) {
        return NGX_DECLINED;
    }

    /* reject requests with "User-Agent: foo" */
    if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) {
        return NGX_HTTP_FORBIDDEN;
    }

    return NGX_DECLINED;
}


static ngx_int_t
ngx_http_foo_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt        *h;
    ngx_http_core_main_conf_t  *cmcf;

    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

    h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    *h = ngx_http_foo_handler;

    return NGX_OK;
}

フェーズハンドラは特定のコードを返すことを期待されます:

幾つかのフェーズは戻りコードを少し異なった方法で扱います。コンテントフェーズでは、NGX_DECLINED以外のどのようなコードも終了コードと見なされます。locationコンテントハンドラについては、それらからのどのような返り値も終了コードと見なされます。satisfy any モードのアクセスフェーズでは、NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE 以外の戻りコードは拒否と見なされます。将来のアクセスハンドラのいずれもが新しいコードでアクセスあるいは拒否しない場合は、拒否コードが終了コードになるでしょう。

変数

既存の変数へのアクセス

変数はインデックス(これは最も一般的な方法です)あるいは名前(変数の生成については以下の章を見てください)を使って参照することができます。インデックスは変数が設定に追加される時に設定ステージで生成されます。変数のインデックスはngx_http_get_variable_index()を使って取得することができます:

ngx_str_t  name;  /* ngx_string("foo") */
ngx_int_t  index;

index = ngx_http_get_variable_index(cf, &name);

ここで、cf はnginxの設定へのポインタで、name は変数名を持つ文字列へのポインタです。関数はエラー時にNGX_ERROR を返すか、そうでなければ有効なインデックスを返します。これは一般的に後で使うためにモジュール内のどこかに格納されます。

全てのHTTP変数はHTTPリクエストのコンテキスト内で評価され、結果はHTTPリクエストに固有でその中にキャッシュされます。変数を評価する全ての関数はngx_http_variable_value_t型を返し、変数の値を表します:

typedef ngx_variable_value_t  ngx_http_variable_value_t;

typedef struct {
    unsigned    len:28;

    unsigned    valid:1;
    unsigned    no_cacheable:1;
    unsigned    not_found:1;
    unsigned    escape:1;

    u_char     *data;
} ngx_variable_value_t;

ここで:

ngx_http_get_flushed_variable()ngx_http_get_indexed_variable() 関数は変数の値を取得するために使われます。それらは同じインタフェースを持ちます - HTTP リクエスト r を変数を評価するためのコンテキストとして受け取り、それを識別するためのindexを受け取ります。一般的な使い方の例:

ngx_http_variable_value_t  *v;

v = ngx_http_get_flushed_variable(r, index);

if (v == NULL || v->not_found) {
    /* we failed to get value or there is no such variable, handle it */
    return NGX_ERROR;
}

/* some meaningful value is found */

関数間の違いはngx_http_get_indexed_variable() はキャッシュされた値を返し、ngx_http_get_flushed_variable() はキャッシュできない変数のためにキャッシュをフラッシュすることです。

例えばSSIあるいはPerlモジュールのように、設定時には名前が知られておらず従ってインデックスを使ってアクセスすることができない変数を扱う必要がある場合があります。ngx_http_get_variable(r, name, key) 関数はそのような場合に使われるかも知れません。指定されたname とそのハッシュkeyを使ってvariable を検索します

変数の作成

変数を作成するためにngx_http_add_variable() 関数が使われます。それは、挙動を制御する設定(ここで変数が登録されます)、変数名およびフラグを取ります:

関数は、エラー時にはNULL、そうでなければngx_http_variable_tへのポインタを返します:

struct ngx_http_variable_s {
    ngx_str_t                     name;
    ngx_http_set_variable_pt      set_handler;
    ngx_http_get_variable_pt      get_handler;
    uintptr_t                     data;
    ngx_uint_t                    flags;
    ngx_uint_t                    index;
};

get および set ハンドラは変数値を取得あるいは設定するために呼ばれ、data は変数ハンドラに渡され、index 変数を参照するために使われる割り当てられた可変のインデックスを持つでしょう。

通常、そのような構造おnullで終わる静的な配列はモジュールによって生成され、変数を設定に追加するために事前設定のステージで処理されます:

static ngx_http_variable_t  ngx_http_foo_vars[] = {

    { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },

    { ngx_null_string, NULL, NULL, 0, 0, 0 }
};

static ngx_int_t
ngx_http_foo_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var, *v;

    for (v = ngx_http_foo_vars; v->name.len; v++) {
        var = ngx_http_add_variable(cf, &v->name, v->flags);
        if (var == NULL) {
            return NGX_ERROR;
        }

        var->get_handler = v->get_handler;
        var->data = v->data;
    }

    return NGX_OK;
}

この関数はHTTPモジュールのコンテキストのpreconfiguration フィールドを初期化するために使われ、HTTP設定をパースする前に呼ばれます。つまり、それはこれらの変数を参照することができます。

get ハンドラは特定のリクエストのコンテキストの中で変数を評価する責任があります。例えば:

static ngx_int_t
ngx_http_variable_connection(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data)
{
    u_char  *p;

    p = ngx_pnalloc(r->pool, NGX_ATOMIC_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->len = ngx_sprintf(p, "%uA", r->connection->number) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;
    v->data = p;

    return NGX_OK;
}

内部エラー(例えば、メモリ割り当ての失敗)の場合はNGX_ERROR を返し、そうでなければNGX_OK を返します。変数の評価の状態はngx_http_variable_value_t (上の説明を見てください)のフラグの精査によって理解されるかも知れません。

set ハンドラによって変数によるプロパティの参照を設定することができます。例えば、$limit_rate 変数の設定ハンドラはリクエストの limit_rate フィールドを修正します:

...
{ ngx_string("limit_rate"), ngx_http_variable_request_set_size,
  ngx_http_variable_request_get_size,
  offsetof(ngx_http_request_t, limit_rate),
  NGX_HTTP_VAR_CHANGEABLE|NGX_HTTP_VAR_NOCACHEABLE, 0 },
...

static void
ngx_http_variable_request_set_size(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data)
{
    ssize_t    s, *sp;
    ngx_str_t  val;

    val.len = v->len;
    val.data = v->data;

    s = ngx_parse_size(&val);

    if (s == NGX_ERROR) {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
                      "invalid size \"%V\"", &val);
        return;
    }

    sp = (ssize_t *) ((char *) r + data);

    *sp = s;

    return;
}

comoplex値

複雑な値という名前にも関わらず、それはテキスト、変数およびそれらの組み合わせを含む表現の評価を簡単にする方法を提供します。

ngx_http_compile_complex_value 内のcomplex値の概要は設定ステージにおいて、評価された表現の結果を取得するために実行時に使われるngx_http_complex_value_t へコンパイルされます。

ngx_str_t                         *value;
ngx_http_complex_value_t           cv;
ngx_http_compile_complex_value_t   ccv;

value = cf->args->elts; /* directive arguments */

ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));

ccv.cf = cf;
ccv.value = &value[1];
ccv.complex_value = &cv;
ccv.zero = 1;
ccv.conf_prefix = 1;

if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
    return NGX_CONF_ERROR;
}

ここで、ccv はcomplex値 cvを初期化することを必要とする全てのパラメータを保持します:

The zero flag is usable when results are to be passed to libraries that require zero-terminated strings, and prefixes are handy when dealing with filenames.

Upon successful compilation, cv.lengths may be inspected to get information about the presence of variables in the expression. The NULL value means that the expression contained static text only, and there is no need in storing it as a complex value, so a simple string can be used.

The ngx_http_set_complex_value_slot() is a convenient function used to initialize complex value completely right in the directive declaration.

At runtime, a complex value may be calculated using the ngx_http_complex_value() function:

ngx_str_t  res;

if (ngx_http_complex_value(r, &cv, &res) != NGX_OK) {
    return NGX_ERROR;
}

Given the request r and previously compiled value cv the function will evaluate expression and put result into res.

Response

An HTTP response in nginx is produced by sending the response header followed by the optional response body. Both header and body are passed through a chain of filters and eventually get written to the client socket. An nginx module can install its handler into the header or body filter chain and process the output coming from the previous handler.

Response header

Output header is sent by the function ngx_http_send_header(r). Prior to calling this function, r->headers_out should contain all the data required to produce the HTTP response header. It's always required to set the status field of r->headers_out. If the response status suggests that a response body follows the header, content_length_n can be set as well. The default value for this field is -1, which means that the body size is unknown. In this case, chunked transfer encoding is used. To output an arbitrary header, headers list should be appended.

static ngx_int_t
ngx_http_foo_content_handler(ngx_http_request_t *r)
{
    ngx_int_t         rc;
    ngx_table_elt_t  *h;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    /* X-Foo: foo */

    h = ngx_list_push(&r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&h->key, "X-Foo");
    ngx_str_set(&h->value, "foo");

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    ...
}

Header filters

The ngx_http_send_header(r) function invokes the header filter chain by calling the top header filter handler ngx_http_top_header_filter. It's assumed that every header handler calls the next handler in chain until the final handler ngx_http_header_filter(r) is called. The final header handler constructs the HTTP response based on r->headers_out and passes it to the ngx_http_writer_filter for output.

To add a handler to the header filter chain, one should store its address in ngx_http_top_header_filter global variable at configuration time. The previous handler address is normally stored in a module's static variable and is called by the newly added handler before exiting.

The following is an example header filter module, adding the HTTP header "X-Foo: foo" to every output with the status 200.

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>


static ngx_int_t ngx_http_foo_header_filter(ngx_http_request_t *r);
static ngx_int_t ngx_http_foo_header_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_foo_header_filter_module_ctx = {
    NULL,                                   /* preconfiguration */
    ngx_http_foo_header_filter_init,        /* postconfiguration */

    NULL,                                   /* create main configuration */
    NULL,                                   /* init main configuration */

    NULL,                                   /* create server configuration */
    NULL,                                   /* merge server configuration */

    NULL,                                   /* create location configuration */
    NULL                                    /* merge location configuration */
};


ngx_module_t  ngx_http_foo_header_filter_module = {
    NGX_MODULE_V1,
    &ngx_http_foo_header_filter_module_ctx, /* module context */
    NULL,                                   /* module directives */
    NGX_HTTP_MODULE,                        /* module type */
    NULL,                                   /* init master */
    NULL,                                   /* init module */
    NULL,                                   /* init process */
    NULL,                                   /* init thread */
    NULL,                                   /* exit thread */
    NULL,                                   /* exit process */
    NULL,                                   /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_header_filter_pt  ngx_http_next_header_filter;


static ngx_int_t
ngx_http_foo_header_filter(ngx_http_request_t *r)
{
    ngx_table_elt_t  *h;

    /* 
     * The filter handler adds "X-Foo: foo" header
     * to every HTTP 200 response
     */

    if (r->headers_out.status != NGX_HTTP_OK) {
        return ngx_http_next_header_filter(r);
    }

    h = ngx_list_push(&r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&h->key, "X-Foo");
    ngx_str_set(&h->value, "foo");

    return ngx_http_next_header_filter(r);
}


static ngx_int_t
ngx_http_foo_header_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_header_filter = ngx_http_top_header_filter;
    ngx_http_top_header_filter = ngx_http_foo_header_filter;

    return NGX_OK;
}

Response body

Response body is sent by calling the function ngx_http_output_filter(r, cl). The function can be called multiple times. Each time it sends a part of the response body passed as a buffer chain. The last body buffer should have the last_buf flag set.

The following example produces a complete HTTP output with "foo" as its body. In order for the example to work not only as a main request but as a subrequest as well, the last_in_chain_flag is set in the last buffer of the output. The last_buf flag is set only for the main request since a subrequest's last buffers does not end the entire output.

static ngx_int_t
ngx_http_bar_content_handler(ngx_http_request_t *r)
{
    ngx_int_t     rc;
    ngx_buf_t    *b;
    ngx_chain_t   out;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    b = ngx_calloc_buf(r->pool);
    if (b == NULL) {
        return NGX_ERROR;
    }

    b->last_buf = (r == r->main) ? 1: 0;
    b->last_in_chain = 1;

    b->memory = 1;

    b->pos = (u_char *) "foo";
    b->last = b->pos + 3;

    out.buf = b;
    out.next = NULL;

    return ngx_http_output_filter(r, &out);
}

Body filters

The function ngx_http_output_filter(r, cl) invokes the body filter chain by calling the top body filter handler ngx_http_top_body_filter. It's assumed that every body handler calls the next handler in chain until the final handler ngx_http_write_filter(r, cl) is called.

A body filter handler receives a chain of buffers. The handler is supposed to process the buffers and pass a possibly new chain to the next handler. It's worth noting that the chain links ngx_chain_t of the incoming chain belong to the caller. They should never be reused or changed. Right after the handler completes, the caller can use its output chain links to keep track of the buffers it has sent. To save the buffer chain or to substitute some buffers before sending further, a handler should allocate its own chain links.

Following is the example of a simple body filter counting the number of body bytes. The result is available as the $counter variable which can be used in the access log.

#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>


typedef struct {
    off_t  count;
} ngx_http_counter_filter_ctx_t;


static ngx_int_t ngx_http_counter_body_filter(ngx_http_request_t *r,
    ngx_chain_t *in);
static ngx_int_t ngx_http_counter_variable(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data);
static ngx_int_t ngx_http_counter_add_variables(ngx_conf_t *cf);
static ngx_int_t ngx_http_counter_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_counter_filter_module_ctx = {
    ngx_http_counter_add_variables,        /* preconfiguration */
    ngx_http_counter_filter_init,          /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


ngx_module_t  ngx_http_counter_filter_module = {
    NGX_MODULE_V1,
    &ngx_http_counter_filter_module_ctx,   /* module context */
    NULL,                                  /* module directives */
    NGX_HTTP_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_body_filter_pt  ngx_http_next_body_filter;

static ngx_str_t  ngx_http_counter_name = ngx_string("counter");


static ngx_int_t
ngx_http_counter_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_chain_t                    *cl;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_counter_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_counter_filter_module);
    }

    for (cl = in; cl; cl = cl->next) {
        ctx->count += ngx_buf_size(cl->buf);
    }

    return ngx_http_next_body_filter(r, in);
}


static ngx_int_t
ngx_http_counter_variable(ngx_http_request_t *r, ngx_http_variable_value_t *v,
    uintptr_t data)
{
    u_char                         *p;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        v->not_found = 1;
        return NGX_OK;
    }

    p = ngx_pnalloc(r->pool, NGX_OFF_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->data = p;
    v->len = ngx_sprintf(p, "%O", ctx->count) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var;

    var = ngx_http_add_variable(cf, &ngx_http_counter_name, 0);
    if (var == NULL) {
        return NGX_ERROR;
    }

    var->get_handler = ngx_http_counter_variable;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_body_filter = ngx_http_top_body_filter;
    ngx_http_top_body_filter = ngx_http_counter_body_filter;

    return NGX_OK;
}

Building filter modules

When writing a body or header filter, a special care should be taken of the filters order. There's a number of header and body filters registered by nginx standard modules. It's important to register a filter module in the right place in respect to other filters. Normally, filters are registered by modules in their postconfiguration handlers. The order in which filters are called is obviously the reverse of when they are registered.

A special slot HTTP_AUX_FILTER_MODULES for third-party filter modules is provided by nginx. To register a filter module in this slot, the ngx_module_type variable should be set to the value of HTTP_AUX_FILTER in module's configuration.

The following example shows a filter module config file assuming it only has one source file ngx_http_foo_filter_module.c

ngx_module_type=HTTP_AUX_FILTER
ngx_module_name=ngx_http_foo_filter_module
ngx_module_srcs="$ngx_addon_dir/ngx_http_foo_filter_module.c"

. auto/module

Buffer reuse

When issuing or altering a stream of buffers, it's often desirable to reuse the allocated buffers. A standard approach widely adopted in nginx code is to keep two buffer chains for this purpose: free and busy. The free chain keeps all free buffers. These buffers can be reused. The busy chain keeps all buffers sent by the current module which are still in use by some other filter handler. A buffer is considered in use if its size is greater than zero. Normally, when a buffer is consumed by a filter, its pos (or file_pos for a file buffer) is moved towards last (file_last for a file buffer). Once a buffer is completely consumed, it's ready to be reused. To update the free chain with newly freed buffers, it's enough to iterate over the busy chain and move the zero size buffers at the head of it to free. This operation is so common that there is a special function ngx_chain_update_chains(free, busy, out, tag) which does this. The function appends the output chain out to busy and moves free buffers from the top of busy to free. Only the buffers with the given tag are reused. This lets a module reuse only the buffers allocated by itself.

The following example is a body filter inserting the “foo” string before each incoming buffer. The new buffers allocated by the module are reused if possible. Note that for this example to work properly, it's also required to set up a header filter and reset content_length_n to -1, which is beyond the scope of this section.

typedef struct {
    ngx_chain_t  *free;
    ngx_chain_t  *busy;
}  ngx_http_foo_filter_ctx_t;


ngx_int_t
ngx_http_foo_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_int_t                   rc;
    ngx_buf_t                  *b;
    ngx_chain_t                *cl, *tl, *out, **ll;
    ngx_http_foo_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_foo_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_foo_filter_module);
    }

    /* create a new chain "out" from "in" with all the changes */

    ll = &out;

    for (cl = in; cl; cl = cl->next) {

        /* append "foo" in a reused buffer if possible */

        tl = ngx_chain_get_free_buf(r->pool, &ctx->free);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        b = tl->buf;
        b->tag = (ngx_buf_tag_t) &ngx_http_foo_filter_module;
        b->memory = 1;
        b->pos = (u_char *) "foo";
        b->last = b->pos + 3;

        *ll = tl;
        ll = &tl->next;

        /* append the next incoming buffer */

        tl = ngx_alloc_chain_link(r->pool);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        tl->buf = cl->buf;
        *ll = tl;
        ll = &tl->next;
    }

    *ll = NULL;

    /* send the new chain */

    rc = ngx_http_next_body_filter(r, out);

    /* update "busy" and "free" chains for reuse */

    ngx_chain_update_chains(r->pool, &ctx->free, &ctx->busy, &out,
                            (ngx_buf_tag_t) &ngx_http_foo_filter_module);

    return rc;
}

Load balancing

The ngx_http_upstream_module provides basic functionality to pass requests to remote servers. This functionality is used by modules that implement specific protocols, such as HTTP or FastCGI. The module also provides an interface for creating custom load balancing modules and implements a default round-robin balancing method.

Examples of modules that implement alternative load balancing methods are least_conn and hash. Note that these modules are actually implemented as extensions of the upstream module and share a lot of code, such as representation of a server group. The keepalive module is an example of an independent module, extending upstream functionality.

The ngx_http_upstream_module may be configured explicitly by placing the corresponding upstream block into the configuration file, or implicitly by using directives that accept a URL evaluated at some point to the list of servers, for example, proxy_pass. Only explicit configurations may use an alternative load balancing method. The upstream module configuration has its own directive context NGX_HTTP_UPS_CONF. The structure is defined as follows:

struct ngx_http_upstream_srv_conf_s {
    ngx_http_upstream_peer_t         peer;
    void                           **srv_conf;

    ngx_array_t                     *servers;  /* ngx_http_upstream_server_t */

    ngx_uint_t                       flags;
    ngx_str_t                        host;
    u_char                          *file_name;
    ngx_uint_t                       line;
    in_port_t                        port;
    ngx_uint_t                       no_port;  /* unsigned no_port:1 */

#if (NGX_HTTP_UPSTREAM_ZONE)
    ngx_shm_zone_t                  *shm_zone;
#endif
};

When nginx has to pass a request to another host for processing, it uses a configured load balancing method to obtain an address to connect to. The method is taken from the ngx_http_upstream_peer_t.peer object of type ngx_peer_connection_t:

struct ngx_peer_connection_s {
    [...]

    struct sockaddr                 *sockaddr;
    socklen_t                        socklen;
    ngx_str_t                       *name;

    ngx_uint_t                       tries;

    ngx_event_get_peer_pt            get;
    ngx_event_free_peer_pt           free;
    ngx_event_notify_peer_pt         notify;
    void                            *data;

#if (NGX_SSL || NGX_COMPAT)
    ngx_event_set_peer_session_pt    set_session;
    ngx_event_save_peer_session_pt   save_session;
#endif

    [..]
};

The structure has the following fields:

All methods accept at least two arguments: peer connection object pc and the data created by ngx_http_upstream_srv_conf_t.peer.init(). Note that in general case it may differ from pc.data due to “chaining” of load balancing modules.

TOP
inserted by FC2 system