changeset 3007:3184864bbb3f

Added SharedDict to njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 16 Aug 2023 12:12:22 +0100
parents 0e805229dd19
children 4470b2bff7b7
files xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/njs/changes.xml xml/en/docs/njs/compatibility.xml xml/en/docs/njs/reference.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/njs/compatibility.xml xml/ru/docs/stream/ngx_stream_js_module.xml
diffstat 8 files changed, 279 insertions(+), 13 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="40">
+        rev="41">
 
 <section id="summary">
 
@@ -637,7 +637,8 @@ since <link doc="../njs/changes.xml" id=
 
 <para>
 Sets the <value>name</value> and <value>size</value> of the shared memory zone
-that keeps the key-value dictionary
+that keeps the
+key-value <link doc="../njs/reference.xml" id="dict">dictionary</link>
 shared between worker processes.
 </para>
 
--- a/xml/en/docs/njs/changes.xml
+++ b/xml/en/docs/njs/changes.xml
@@ -9,7 +9,7 @@
 <article name="Changes"
         link="/en/docs/njs/changes.html"
         lang="en"
-        rev="62"
+        rev="63"
         toc="no">
 
 <section id="njs0.8.0" name="Changes with njs 0.8.0">
@@ -59,7 +59,8 @@ module.
 <listitem>
 <para>
 Feature:
-introduced global nginx properties:
+introduced more global
+<link doc="reference.xml" id="ngx"><literal>nginx</literal></link> properties:
 <link doc="reference.xml" id="ngx_build"><literal>ngx.build</literal></link>,
 <link doc="reference.xml" id="ngx_conf_file_path"><literal>ngx.conf_file_path</literal></link>,
 <link doc="reference.xml" id="ngx_error_log_path"><literal>ngx.error_log_path</literal></link>,
@@ -84,6 +85,15 @@ that allows declaring a dictionary share
 
 <listitem>
 <para>
+Feature:
+introduced global
+<link doc="reference.xml" id="ngx_shared"><literal>nginx.shared</literal></link>
+methods and properties for working with shared dictionaries.
+</para>
+</listitem>
+
+<listitem>
+<para>
 Improvement:
 added compile-time options to disable njs modules.
 For example, to disable libxslt-related code:
--- a/xml/en/docs/njs/compatibility.xml
+++ b/xml/en/docs/njs/compatibility.xml
@@ -9,7 +9,7 @@
 <article name="Compatibility"
         link="/en/docs/njs/compatibility.html"
         lang="en"
-        rev="39"
+        rev="40"
         toc="no">
 
 <section>
@@ -1116,6 +1116,23 @@ nginx object methods:
 <link doc="reference.xml" id="ngx_log"><literal>log</literal></link>
 </listitem>
 
+<listitem>
+<link doc="reference.xml" id="ngx_shared"><literal>ngx.shared</literal></link>
+(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>):
+<link doc="reference.xml" id="dict_add"><literal>add</literal></link>,
+<link doc="reference.xml" id="dict_clear"><literal>clear</literal></link>,
+<link doc="reference.xml" id="dict_delete"><literal>delete</literal></link>,
+<link doc="reference.xml" id="dict_incr"><literal>incr</literal></link>,
+<link doc="reference.xml" id="dict_freespace"><literal>freeSpace</literal></link>,
+<link doc="reference.xml" id="dict_get"><literal>get</literal></link>,
+<link doc="reference.xml" id="dict_has"><literal>has</literal></link>,
+<link doc="reference.xml" id="dict_keys"><literal>keys</literal></link>,
+<link doc="reference.xml" id="dict_pop"><literal>pop</literal></link>,
+<link doc="reference.xml" id="dict_replace"><literal>replace</literal></link>,
+<link doc="reference.xml" id="dict_set"><literal>set</literal></link>,
+<link doc="reference.xml" id="dict_size"><literal>size</literal></link>
+</listitem>
+
 </list>
 </listitem>
 
@@ -1207,6 +1224,14 @@ nginx object properties:
 (<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
 </listitem>
 
+<listitem>
+<link doc="reference.xml" id="ngx_shared"><literal>ngx.shared</literal></link>
+(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>):
+<link doc="reference.xml" id="dict_capacity"><literal>capacity</literal></link>,
+<link doc="reference.xml" id="dict_name"><literal>name</literal></link>,
+<link doc="reference.xml" id="dict_name"><literal>type</literal></link>
+</listitem>
+
 </list>
 </listitem>
 
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Reference"
         link="/en/docs/njs/reference.html"
         lang="en"
-        rev="114">
+        rev="115">
 
 <section id="summary">
 
@@ -1584,6 +1584,208 @@ the value is between <literal>0</literal
 
 </section>
 
+<section id="ngx_shared" name="ngx.shared">
+
+<para>
+The <literal>ngx.shared</literal> global object is available
+since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
+</para>
+
+
+<section id="dict" name="SharedDict">
+<para>
+<table width="100%">
+<tr><td><link id="dict_add"><literal>ngx.shared.SharedDict.add()</literal></link></td></tr>
+<tr><td><link id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></link></td></tr>
+<tr><td><link id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></link></td></tr>
+<tr><td><link id="dict_delete"><literal>ngx.shared.SharedDict.delete()</literal></link></td></tr>
+<tr><td><link id="dict_incr"><literal>ngx.shared.SharedDict.incr()</literal></link></td></tr>
+<tr><td><link id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></link></td></tr>
+<tr><td><link id="dict_get"><literal>ngx.shared.SharedDict.get()</literal></link></td></tr>
+<tr><td><link id="dict_has"><literal>ngx.shared.SharedDict.has()</literal></link></td></tr>
+<tr><td><link id="dict_keys"><literal>ngx.shared.SharedDict.keys()</literal></link></td></tr>
+<tr><td><link id="dict_name"><literal>ngx.shared.SharedDict.name</literal></link></td></tr>
+<tr><td><link id="dict_pop"><literal>ngx.shared.SharedDict.pop()</literal></link></td></tr>
+<tr><td><link id="dict_replace"><literal>ngx.shared.SharedDict.replace()</literal></link></td></tr>
+<tr><td><link id="dict_set"><literal>ngx.shared.SharedDict.set()</literal></link></td></tr>
+<tr><td><link id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></link></td></tr>
+<tr><td><link id="dict_type"><literal>ngx.shared.SharedDict.type</literal></link></td></tr>
+</table>
+</para>
+
+<para>
+The shared dictionary object is available
+since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
+The shared dictionary name, type, and size
+are set with the <literal>js_shared_dict_zone</literal> directive in
+<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
+or
+<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
+</para>
+
+<para>
+A <literal>SharedDict()</literal> object
+has the following properties and methods:
+<list type="tag">
+
+<tag-name id="dict_add"><literal>ngx.shared.SharedDict.add(<value>key</value>,
+<value>value</value>)</literal></tag-name>
+<tag-desc>
+Sets the <literal>value</literal>
+for the specified <literal>key</literal> in the dictionary
+only if the key does not exist yet.
+The <literal>key</literal> is a string representing
+the key of the item to add,
+the <literal>value</literal> is the value of the item to add.
+Returns <literal>true</literal> if the value has been successfully added
+to  the <literal>SharedDict</literal> dictionary,
+<literal>false</literal> if the key already exists in the dictionary.
+Throws <literal>SharedMemoryError</literal> if
+there is not enough free space in the <literal>SharedDict</literal> dictionary.
+Throws <literal>TypeError</literal> if the <literal>value</literal> is
+of a different type than expected by this dictionary.
+</tag-desc>
+
+<tag-name id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></tag-name>
+<tag-desc>
+Returns the capacity of the <literal>SharedDict</literal> dictionary,
+corresponds to the <literal>size</literal> parameter of
+<literal>js_shared_dict_zone</literal> directive in
+<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
+or
+<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
+</tag-desc>
+
+<tag-name id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></tag-name>
+<tag-desc>
+Removes all items from the <literal>SharedDict</literal> dictionary.
+</tag-desc>
+
+<tag-name id="dict_delete"><literal>ngx.shared.SharedDict.delete(<value>key</value>)</literal></tag-name>
+<tag-desc>
+Removes the item associated with the specified key
+from the <literal>SharedDict</literal> dictionary,
+<literal>true</literal> if the item in the dictionary existed and was removed,
+<literal>false</literal> otherwise.
+</tag-desc>
+
+<tag-name id="dict_incr"><literal>ngx.shared.SharedDict.incr(<value>key</value>,<value>delta</value>[,<value>init</value>])</literal></tag-name>
+<tag-desc>
+Increments the integer value associated with the <literal>key</literal>
+by <literal>delta</literal>.
+If the key does not exist,
+the item will be initialized to <literal>init</literal>.
+The <literal>key</literal> is a string,
+the <literal>delta</literal> is the number
+to increment or decrement the value by,
+the <literal>init</literal> is a number to initialize the item with
+if it does not exist, by default is <literal>0</literal>.
+Returns the new value.
+Throws <literal>SharedMemoryError</literal> if
+there is not enough free space in the <literal>SharedDict</literal> dictionary.
+Throws <literal>TypeError</literal> if this dictionary does not expect numbers.
+<note>
+This method can be used only if the dictionary type was declared with
+<literal>type=number</literal> parameter of the
+<literal>js_shared_dict_zone</literal> directive in
+<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
+or
+<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
+</note>
+</tag-desc>
+
+<tag-name id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></tag-name>
+<tag-desc>
+Returns the free page size in bytes.
+If the size is zero, the <literal>SharedDict</literal> dictionary
+will still accept new values if there is space in the occupied pages.
+</tag-desc>
+
+<tag-name id="dict_get"><literal>ngx.shared.SharedDict.get(<value>key</value>)</literal></tag-name>
+<tag-desc>
+Retrieves the item by its <literal>key</literal>,
+returns the value associated with the <literal>key</literal>
+or <literal>undefined</literal> if there is none.
+</tag-desc>
+
+<tag-name id="dict_has"><literal>ngx.shared.SharedDict.has(<value>key</value>)</literal></tag-name>
+<tag-desc>
+Searches for an item by its <literal>key</literal>,
+returns <literal>true</literal> if such item exists or
+<literal>false</literal> otherwise.
+</tag-desc>
+
+<tag-name id="dict_keys"><literal>ngx.shared.SharedDict.keys([<value>maxCount</value>])</literal></tag-name>
+<tag-desc>
+Returns an array of the <literal>SharedDict</literal> dictionary keys.
+The <literal>maxCount</literal> parameter
+sets maximum number of keys to retrieve,
+by default is <literal>1024</literal>.
+
+</tag-desc>
+
+<tag-name id="dict_name"><literal>ngx.shared.SharedDict.name</literal></tag-name>
+<tag-desc>
+Returns the name of the <literal>SharedDict</literal> dictionary,
+corresponds to the <literal>zone=</literal> parameter of
+<literal>js_shared_dict_zone</literal> directive in
+<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
+or
+<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
+</tag-desc>
+
+<tag-name id="dict_pop"><literal>ngx.shared.SharedDict.pop(<value>key</value>)</literal></tag-name>
+<tag-desc>
+Removes the item associated with the specified <literal>key</literal>
+from the <literal>SharedDict</literal> dictionary,
+returns the value associated with the <literal>key</literal>
+or <literal>undefined</literal> if there is none.
+</tag-desc>
+
+<tag-name id="dict_replace"><literal>ngx.shared.SharedDict.replace(<value>key</value>,
+<value>value</value>)</literal></tag-name>
+<tag-desc>
+Replaces the <literal>value</literal>
+for the specified <literal>key</literal> only if the key already exists,
+returns <literal>true</literal> if the value was successfully replaced,
+<literal>false</literal> if the key does not exist
+in the <literal>SharedDict</literal> dictionary.
+Throws <literal>SharedMemoryError</literal> if
+there is not enough free space in the <literal>SharedDict</literal> dictionary.
+Throws <literal>TypeError</literal> if the <literal>value</literal> is
+of a different type than expected by this dictionary.
+</tag-desc>
+
+<tag-name id="dict_set"><literal>ngx.shared.SharedDict.set(<value>key</value>,
+<value>value</value>)</literal></tag-name>
+<tag-desc>
+Sets the <literal>value</literal> for the specified <literal>key</literal>,
+returns this <literal>SharedDict</literal> dictionary (for method chaining).
+</tag-desc>
+
+<tag-name id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></tag-name>
+<tag-desc>
+Returns the number of items for the <literal>SharedDict</literal> dictionary.
+</tag-desc>
+
+<tag-name id="dict_type"><literal>ngx.shared.SharedDict.type</literal></tag-name>
+<tag-desc>
+Returns <literal>string</literal> or <literal>number</literal> that
+corresponds to the <literal>SharedDict</literal> dictionary type
+set by the <literal>type=</literal> parameter of
+<literal>js_shared_dict_zone</literal> directive in
+<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
+or
+<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+</section>
+
 </section>
 
 
--- 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="38">
+        rev="39">
 
 <section id="summary">
 
@@ -622,7 +622,8 @@ since <link doc="../njs/changes.xml" id=
 
 <para>
 Sets the <value>name</value> and <value>size</value> of the shared memory zone
-that keeps the key-value dictionary
+that keeps the
+key-value <link doc="../njs/reference.xml" id="dict">dictionary</link>
 shared between worker processes.
 </para>
 
--- 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="40">
+        rev="41">
 
 <section id="summary">
 
@@ -638,7 +638,8 @@ js_preload_object map.json;
 
 <para>
 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
-в которой хранится словарь ключей и значений,
+в которой хранится
+<link doc="../njs/reference.xml" id="dict">словарь</link> ключей и значений,
 разделяемый между рабочими процессами.
 </para>
 
--- a/xml/ru/docs/njs/compatibility.xml
+++ b/xml/ru/docs/njs/compatibility.xml
@@ -9,7 +9,7 @@
 <article name="Совместимость"
         link="/ru/docs/njs/compatibility.html"
         lang="ru"
-        rev="39"
+        rev="40"
         toc="no">
 
 <section>
@@ -1116,6 +1116,23 @@ ES6 поддержка стрелочных функций
 <link doc="reference.xml" id="ngx_log"><literal>log</literal></link>
 </listitem>
 
+<listitem>
+<link doc="reference.xml" id="ngx_shared"><literal>ngx.shared</literal></link>
+(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>):
+<link doc="reference.xml" id="dict_add"><literal>add</literal></link>,
+<link doc="reference.xml" id="dict_clear"><literal>clear</literal></link>,
+<link doc="reference.xml" id="dict_delete"><literal>delete</literal></link>,
+<link doc="reference.xml" id="dict_incr"><literal>incr</literal></link>,
+<link doc="reference.xml" id="dict_freespace"><literal>freeSpace</literal></link>,
+<link doc="reference.xml" id="dict_get"><literal>get</literal></link>,
+<link doc="reference.xml" id="dict_has"><literal>has</literal></link>,
+<link doc="reference.xml" id="dict_keys"><literal>keys</literal></link>,
+<link doc="reference.xml" id="dict_pop"><literal>pop</literal></link>,
+<link doc="reference.xml" id="dict_replace"><literal>replace</literal></link>,
+<link doc="reference.xml" id="dict_set"><literal>set</literal></link>,
+<link doc="reference.xml" id="dict_size"><literal>size</literal></link>
+</listitem>
+
 </list>
 </listitem>
 
@@ -1207,6 +1224,14 @@ ES6 поддержка стрелочных функций
 (<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
 </listitem>
 
+<listitem>
+<link doc="reference.xml" id="ngx_shared"><literal>ngx.shared</literal></link>
+(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>):
+<link doc="reference.xml" id="dict_capacity"><literal>capacity</literal></link>,
+<link doc="reference.xml" id="dict_name"><literal>name</literal></link>,
+<link doc="reference.xml" id="dict_name"><literal>type</literal></link>
+</listitem>
+
 </list>
 </listitem>
 
--- 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="38">
+        rev="39">
 
 <section id="summary">
 
@@ -621,7 +621,8 @@ js_preload_object map.json;
 
 <para>
 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
-в которой хранится словарь ключей и значений,
+в которой хранится
+<link doc="../njs/reference.xml" id="dict">словарь</link> ключей и значений,
 разделяемый между рабочими процессами.
 </para>