Mercurial > hg > nginx-site
diff xml/en/docs/njs/reference.xml @ 3007:3184864bbb3f
Added SharedDict to njs Reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 16 Aug 2023 12:12:22 +0100 |
parents | 7c3182a95cd6 |
children | 2e8c1384d211 |
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml Sat Sep 02 13:01:52 2023 -0400 +++ b/xml/en/docs/njs/reference.xml Wed Aug 16 12:12:22 2023 +0100 @@ -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 @@ </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>