Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 3007:3184864bbb3f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added SharedDict to njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 16 Aug 2023 12:12:22 +0100
parents 7c3182a95cd6
children 2e8c1384d211
comparison
equal deleted inserted replaced
3006:0e805229dd19 3007:3184864bbb3f
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="114"> 12 rev="115">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
1579 (<link doc="changes.xml" id="njs0.8.0">0.8.0</link>) 1579 (<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
1580 </tag-desc> 1580 </tag-desc>
1581 1581
1582 </list> 1582 </list>
1583 </para> 1583 </para>
1584
1585 </section>
1586
1587 <section id="ngx_shared" name="ngx.shared">
1588
1589 <para>
1590 The <literal>ngx.shared</literal> global object is available
1591 since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
1592 </para>
1593
1594
1595 <section id="dict" name="SharedDict">
1596 <para>
1597 <table width="100%">
1598 <tr><td><link id="dict_add"><literal>ngx.shared.SharedDict.add()</literal></link></td></tr>
1599 <tr><td><link id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></link></td></tr>
1600 <tr><td><link id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></link></td></tr>
1601 <tr><td><link id="dict_delete"><literal>ngx.shared.SharedDict.delete()</literal></link></td></tr>
1602 <tr><td><link id="dict_incr"><literal>ngx.shared.SharedDict.incr()</literal></link></td></tr>
1603 <tr><td><link id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></link></td></tr>
1604 <tr><td><link id="dict_get"><literal>ngx.shared.SharedDict.get()</literal></link></td></tr>
1605 <tr><td><link id="dict_has"><literal>ngx.shared.SharedDict.has()</literal></link></td></tr>
1606 <tr><td><link id="dict_keys"><literal>ngx.shared.SharedDict.keys()</literal></link></td></tr>
1607 <tr><td><link id="dict_name"><literal>ngx.shared.SharedDict.name</literal></link></td></tr>
1608 <tr><td><link id="dict_pop"><literal>ngx.shared.SharedDict.pop()</literal></link></td></tr>
1609 <tr><td><link id="dict_replace"><literal>ngx.shared.SharedDict.replace()</literal></link></td></tr>
1610 <tr><td><link id="dict_set"><literal>ngx.shared.SharedDict.set()</literal></link></td></tr>
1611 <tr><td><link id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></link></td></tr>
1612 <tr><td><link id="dict_type"><literal>ngx.shared.SharedDict.type</literal></link></td></tr>
1613 </table>
1614 </para>
1615
1616 <para>
1617 The shared dictionary object is available
1618 since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
1619 The shared dictionary name, type, and size
1620 are set with the <literal>js_shared_dict_zone</literal> directive in
1621 <link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
1622 or
1623 <link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
1624 </para>
1625
1626 <para>
1627 A <literal>SharedDict()</literal> object
1628 has the following properties and methods:
1629 <list type="tag">
1630
1631 <tag-name id="dict_add"><literal>ngx.shared.SharedDict.add(<value>key</value>,
1632 <value>value</value>)</literal></tag-name>
1633 <tag-desc>
1634 Sets the <literal>value</literal>
1635 for the specified <literal>key</literal> in the dictionary
1636 only if the key does not exist yet.
1637 The <literal>key</literal> is a string representing
1638 the key of the item to add,
1639 the <literal>value</literal> is the value of the item to add.
1640 Returns <literal>true</literal> if the value has been successfully added
1641 to the <literal>SharedDict</literal> dictionary,
1642 <literal>false</literal> if the key already exists in the dictionary.
1643 Throws <literal>SharedMemoryError</literal> if
1644 there is not enough free space in the <literal>SharedDict</literal> dictionary.
1645 Throws <literal>TypeError</literal> if the <literal>value</literal> is
1646 of a different type than expected by this dictionary.
1647 </tag-desc>
1648
1649 <tag-name id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></tag-name>
1650 <tag-desc>
1651 Returns the capacity of the <literal>SharedDict</literal> dictionary,
1652 corresponds to the <literal>size</literal> parameter of
1653 <literal>js_shared_dict_zone</literal> directive in
1654 <link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
1655 or
1656 <link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
1657 </tag-desc>
1658
1659 <tag-name id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></tag-name>
1660 <tag-desc>
1661 Removes all items from the <literal>SharedDict</literal> dictionary.
1662 </tag-desc>
1663
1664 <tag-name id="dict_delete"><literal>ngx.shared.SharedDict.delete(<value>key</value>)</literal></tag-name>
1665 <tag-desc>
1666 Removes the item associated with the specified key
1667 from the <literal>SharedDict</literal> dictionary,
1668 <literal>true</literal> if the item in the dictionary existed and was removed,
1669 <literal>false</literal> otherwise.
1670 </tag-desc>
1671
1672 <tag-name id="dict_incr"><literal>ngx.shared.SharedDict.incr(<value>key</value>,<value>delta</value>[,<value>init</value>])</literal></tag-name>
1673 <tag-desc>
1674 Increments the integer value associated with the <literal>key</literal>
1675 by <literal>delta</literal>.
1676 If the key does not exist,
1677 the item will be initialized to <literal>init</literal>.
1678 The <literal>key</literal> is a string,
1679 the <literal>delta</literal> is the number
1680 to increment or decrement the value by,
1681 the <literal>init</literal> is a number to initialize the item with
1682 if it does not exist, by default is <literal>0</literal>.
1683 Returns the new value.
1684 Throws <literal>SharedMemoryError</literal> if
1685 there is not enough free space in the <literal>SharedDict</literal> dictionary.
1686 Throws <literal>TypeError</literal> if this dictionary does not expect numbers.
1687 <note>
1688 This method can be used only if the dictionary type was declared with
1689 <literal>type=number</literal> parameter of the
1690 <literal>js_shared_dict_zone</literal> directive in
1691 <link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
1692 or
1693 <link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
1694 </note>
1695 </tag-desc>
1696
1697 <tag-name id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></tag-name>
1698 <tag-desc>
1699 Returns the free page size in bytes.
1700 If the size is zero, the <literal>SharedDict</literal> dictionary
1701 will still accept new values if there is space in the occupied pages.
1702 </tag-desc>
1703
1704 <tag-name id="dict_get"><literal>ngx.shared.SharedDict.get(<value>key</value>)</literal></tag-name>
1705 <tag-desc>
1706 Retrieves the item by its <literal>key</literal>,
1707 returns the value associated with the <literal>key</literal>
1708 or <literal>undefined</literal> if there is none.
1709 </tag-desc>
1710
1711 <tag-name id="dict_has"><literal>ngx.shared.SharedDict.has(<value>key</value>)</literal></tag-name>
1712 <tag-desc>
1713 Searches for an item by its <literal>key</literal>,
1714 returns <literal>true</literal> if such item exists or
1715 <literal>false</literal> otherwise.
1716 </tag-desc>
1717
1718 <tag-name id="dict_keys"><literal>ngx.shared.SharedDict.keys([<value>maxCount</value>])</literal></tag-name>
1719 <tag-desc>
1720 Returns an array of the <literal>SharedDict</literal> dictionary keys.
1721 The <literal>maxCount</literal> parameter
1722 sets maximum number of keys to retrieve,
1723 by default is <literal>1024</literal>.
1724
1725 </tag-desc>
1726
1727 <tag-name id="dict_name"><literal>ngx.shared.SharedDict.name</literal></tag-name>
1728 <tag-desc>
1729 Returns the name of the <literal>SharedDict</literal> dictionary,
1730 corresponds to the <literal>zone=</literal> parameter of
1731 <literal>js_shared_dict_zone</literal> directive in
1732 <link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
1733 or
1734 <link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
1735 </tag-desc>
1736
1737 <tag-name id="dict_pop"><literal>ngx.shared.SharedDict.pop(<value>key</value>)</literal></tag-name>
1738 <tag-desc>
1739 Removes the item associated with the specified <literal>key</literal>
1740 from the <literal>SharedDict</literal> dictionary,
1741 returns the value associated with the <literal>key</literal>
1742 or <literal>undefined</literal> if there is none.
1743 </tag-desc>
1744
1745 <tag-name id="dict_replace"><literal>ngx.shared.SharedDict.replace(<value>key</value>,
1746 <value>value</value>)</literal></tag-name>
1747 <tag-desc>
1748 Replaces the <literal>value</literal>
1749 for the specified <literal>key</literal> only if the key already exists,
1750 returns <literal>true</literal> if the value was successfully replaced,
1751 <literal>false</literal> if the key does not exist
1752 in the <literal>SharedDict</literal> dictionary.
1753 Throws <literal>SharedMemoryError</literal> if
1754 there is not enough free space in the <literal>SharedDict</literal> dictionary.
1755 Throws <literal>TypeError</literal> if the <literal>value</literal> is
1756 of a different type than expected by this dictionary.
1757 </tag-desc>
1758
1759 <tag-name id="dict_set"><literal>ngx.shared.SharedDict.set(<value>key</value>,
1760 <value>value</value>)</literal></tag-name>
1761 <tag-desc>
1762 Sets the <literal>value</literal> for the specified <literal>key</literal>,
1763 returns this <literal>SharedDict</literal> dictionary (for method chaining).
1764 </tag-desc>
1765
1766 <tag-name id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></tag-name>
1767 <tag-desc>
1768 Returns the number of items for the <literal>SharedDict</literal> dictionary.
1769 </tag-desc>
1770
1771 <tag-name id="dict_type"><literal>ngx.shared.SharedDict.type</literal></tag-name>
1772 <tag-desc>
1773 Returns <literal>string</literal> or <literal>number</literal> that
1774 corresponds to the <literal>SharedDict</literal> dictionary type
1775 set by the <literal>type=</literal> parameter of
1776 <literal>js_shared_dict_zone</literal> directive in
1777 <link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
1778 or
1779 <link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
1780 </tag-desc>
1781
1782 </list>
1783 </para>
1784
1785 </section>
1584 1786
1585 </section> 1787 </section>
1586 1788
1587 </section> 1789 </section>
1588 1790