Mercurial > hg > nginx-site

changeset 2990:7e83ebfac8ca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the js_shared_dict_zone directive.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 06 Jul 2023 12:31:31 +0100
parents 703d3450cd81
children 1f672755959a
files xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/stream/ngx_stream_js_module.xml
diffstat 4 files changed, 280 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_js_module.xml
+++ b/xml/en/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_http_js_module"
         link="/en/docs/http/ngx_http_js_module.html"
         lang="en"
-        rev="37">
+        rev="38">
 
 <section id="summary">
 
@@ -623,6 +623,75 @@ since <link doc="../njs/changes.xml" id=
 </directive>
 
 
+<directive name="js_shared_dict_zone">
+<syntax>
+    <literal>zone</literal>=<value>name</value>:<value>size</value>
+    [<literal>timeout</literal>=<value>time</value>]
+    [<literal>type</literal>=<literal>string</literal>|<literal>number</literal>]
+    [<literal>evict</literal>]</syntax>
+<default/>
+<context>http</context>
+<appeared-in>0.8.0</appeared-in>
+
+<para>
+Sets the <value>name</value> and <value>size</value> of the shared memory zone
+that keeps the key-value dictionary
+shared between worker processes.
+</para>
+
+<para>
+By default the shared dictionary uses a string as a key and a value.
+The optional <literal>type</literal> parameter
+allows redefining the value type to number.
+</para>
+
+<para>
+The optional <literal>timeout</literal> parameter sets
+the time after which all shared dictionary entries are removed from the zone.
+</para>
+
+<para>
+The optional <literal>evict</literal> parameter removes the oldest
+key-value pair when the zone storage is exhausted.
+</para>
+
+<para>
+Examples:
+<example>
+example.conf:
+    # Creates a 1Mb dictionary with string values,
+    # removes key-value pairs after 60 seconds of inactivity:
+    js_shared_dict_zone zone=foo:1M timeout=60s;
+
+    # Creates a 512Kb dictionary with string values,
+    # forcibly removes oldest key-value pairs when the zone is exhausted:
+    js_shared_dict_zone zone=bar:512K timeout=30s evict;
+
+    # Creates a 32Kb permanent dictionary with number values:
+    js_shared_dict_zone zone=num:32k type=number;
+
+example.js:
+    function get(r) {
+        r.return(200, ngx.shared.foo.get(r.args.key));
+    }
+
+    function set(r) {
+        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
+    }
+
+    function delete(r) {
+        r.return(200, ngx.shared.bar.delete(r.args.key));
+    }
+
+    function increment(r) {
+        r.return(200, ngx.shared.num.incr(r.args.key, 2));
+    }
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_var">
 <syntax><value>$variable</value> [<value>value</value>]</syntax>
 <default/>
--- a/xml/en/docs/stream/ngx_stream_js_module.xml
+++ b/xml/en/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_stream_js_module"
         link="/en/docs/stream/ngx_stream_js_module.html"
         lang="en"
-        rev="35">
+        rev="36">
 
 <section id="summary">
 
@@ -608,6 +608,75 @@ since <link doc="../njs/changes.xml" id=
 </directive>
 
 
+<directive name="js_shared_dict_zone">
+<syntax>
+    <literal>zone</literal>=<value>name</value>:<value>size</value>
+    [<literal>timeout</literal>=<value>time</value>]
+    [<literal>type</literal>=<literal>string</literal>|<literal>number</literal>]
+    [<literal>evict</literal>]</syntax>
+<default/>
+<context>stream</context>
+<appeared-in>0.8.0</appeared-in>
+
+<para>
+Sets the <value>name</value> and <value>size</value> of the shared memory zone
+that keeps the key-value dictionary
+shared between worker processes.
+</para>
+
+<para>
+By default the shared dictionary uses a string as a key and a value.
+The optional <literal>type</literal> parameter
+allows redefining the value type to number.
+</para>
+
+<para>
+The optional <literal>timeout</literal> parameter sets
+the time after which all shared dictionary entries are removed from the zone.
+</para>
+
+<para>
+The optional <literal>evict</literal> parameter removes the oldest
+key-value pair when the zone storage is exhausted.
+</para>
+
+<para>
+Examples:
+<example>
+example.conf:
+    # Creates a 1Mb dictionary with string values,
+    # removes key-value pairs after 60 seconds of inactivity:
+    js_shared_dict_zone zone=foo:1M timeout=60s;
+
+    # Creates a 512Kb dictionary with string values,
+    # forcibly removes oldest key-value pairs when the zone is exhausted:
+    js_shared_dict_zone zone=bar:512K timeout=30s evict;
+
+    # Creates a 32Kb permanent dictionary with number values:
+    js_shared_dict_zone zone=num:32k type=number;
+
+example.js:
+    function get(r) {
+        r.return(200, ngx.shared.foo.get(r.args.key));
+    }
+
+    function set(r) {
+        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
+    }
+
+    function delete(r) {
+        r.return(200, ngx.shared.bar.delete(r.args.key));
+    }
+
+    function increment(r) {
+        r.return(200, ngx.shared.num.incr(r.args.key, 2));
+    }
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_var">
 <syntax><value>$variable</value> [<value>value</value>]</syntax>
 <default/>
--- a/xml/ru/docs/http/ngx_http_js_module.xml
+++ b/xml/ru/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_http_js_module"
         link="/ru/docs/http/ngx_http_js_module.html"
         lang="ru"
-        rev="37">
+        rev="38">
 
 <section id="summary">
 
@@ -624,6 +624,75 @@ js_preload_object map.json;
 </directive>
 
 
+<directive name="js_shared_dict_zone">
+<syntax>
+    <literal>zone</literal>=<value>имя</value>:<value>размер</value>
+    [<literal>timeout</literal>=<value>время</value>]
+    [<literal>type</literal>=<literal>строка</literal>|<literal>число</literal>]
+    [<literal>evict</literal>]</syntax>
+<default/>
+<context>http</context>
+<appeared-in>0.8.0</appeared-in>
+
+<para>
+Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
+в которой хранится словарь ключей и значений,
+разделяемый между рабочими процессами.
+</para>
+
+<para>
+По умолчанию в качестве ключа и значения используется строка.
+Необязательный параметр <literal>type</literal>
+позволяет изменить тип значения на число.
+</para>
+
+<para>
+Необязательный параметр <literal>timeout</literal> задаёт время,
+по завершении которого все записи в словаре удаляются из зоны.
+</para>
+
+<para>
+Необязательный параметр <literal>evict</literal> удаляет самую старую
+пару ключ-значение при переполнении зоны.
+</para>
+
+<para>
+Пример:
+<example>
+example.conf:
+    # Создаётся словарь размером 1Мб со строковыми значениями,
+    # пары ключ-значение удаляются при отсутствии активности в течение 60 секунд:
+    js_shared_dict_zone zone=foo:1M timeout=60s;
+
+    # Создаётся словарь размером 512Кб со строковыми значениями,
+    # удаляется самая старая пара ключ-значение при переполнении зоны:
+    js_shared_dict_zone zone=bar:512K timeout=30s evict;
+
+    # Создаётся постоянный словарь размером 32Кб с числовыми значениями:
+    js_shared_dict_zone zone=num:32k type=number;
+
+example.js:
+    function get(r) {
+        r.return(200, ngx.shared.foo.get(r.args.key));
+    }
+
+    function set(r) {
+        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
+    }
+
+    function delete(r) {
+        r.return(200, ngx.shared.bar.delete(r.args.key));
+    }
+
+    function increment(r) {
+        r.return(200, ngx.shared.num.incr(r.args.key, 2));
+    }
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_var">
 <syntax><value>$переменная</value> [<value>значение</value>]</syntax>
 <default/>
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_stream_js_module"
         link="/ru/docs/stream/ngx_stream_js_module.html"
         lang="ru"
-        rev="35">
+        rev="36">
 
 <section id="summary">
 
@@ -607,6 +607,75 @@ js_preload_object map.json;
 </directive>
 
 
+<directive name="js_shared_dict_zone">
+<syntax>
+    <literal>zone</literal>=<value>имя</value>:<value>размер</value>
+    [<literal>timeout</literal>=<value>время</value>]
+    [<literal>type</literal>=<literal>строка</literal>|<literal>число</literal>]
+    [<literal>evict</literal>]</syntax>
+<default/>
+<context>stream</context>
+<appeared-in>0.8.0</appeared-in>
+
+<para>
+Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
+в которой хранится словарь ключей и значений,
+разделяемый между рабочими процессами.
+</para>
+
+<para>
+По умолчанию в качестве ключа и значения используется строка.
+Необязательный параметр <literal>type</literal>
+позволяет изменить тип значения на число.
+</para>
+
+<para>
+Необязательный параметр <literal>timeout</literal> задаёт время,
+по завершении которого все записи в словаре удаляются из зоны.
+</para>
+
+<para>
+Необязательный параметр <literal>evict</literal> удаляет самую старую
+пару ключ-значение при переполнении зоны.
+</para>
+
+<para>
+Пример:
+<example>
+example.conf:
+    # Создаётся словарь размером 1Мб со строковыми значениями,
+    # пары ключ-значение удаляются при отсутствии активности в течение 60 секунд:
+    js_shared_dict_zone zone=foo:1M timeout=60s;
+
+    # Создаётся словарь размером 512Кб со строковыми значениями,
+    # удаляется самая старая пара ключ-значение при переполнении зоны:
+    js_shared_dict_zone zone=bar:512K timeout=30s evict;
+
+    # Создаётся постоянный словарь размером 32Кб с числовыми значениями:
+    js_shared_dict_zone zone=num:32k type=number;
+
+example.js:
+    function get(r) {
+        r.return(200, ngx.shared.foo.get(r.args.key));
+    }
+
+    function set(r) {
+        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
+    }
+
+    function delete(r) {
+        r.return(200, ngx.shared.bar.delete(r.args.key));
+    }
+
+    function increment(r) {
+        r.return(200, ngx.shared.num.incr(r.args.key, 2));
+    }
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_var">
 <syntax><value>$переменная</value> [<value>значение</value>]</syntax>
 <default/>