Mercurial > hg > nginx-site
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>