changeset 2984:cc475ba7d406

Added Preload Objects article in njs.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 01 Jun 2023 17:12:18 +0100
parents 67dd348c9757
children 19d3277e4793
files xml/en/GNUmakefile xml/en/docs/njs/index.xml xml/en/docs/njs/preload_objects.xml xml/ru/GNUmakefile xml/ru/docs/njs/index.xml xml/ru/docs/njs/preload_objects.xml
diffstat 6 files changed, 175 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -137,6 +137,7 @@ REFS =									\
 		njs/cli							\
 		njs/compatibility					\
 		njs/install						\
+		njs/preload_objects					\
 		njs/reference						\
 		njs/security						\
 		njs/node_modules					\
--- a/xml/en/docs/njs/index.xml
+++ b/xml/en/docs/njs/index.xml
@@ -9,7 +9,7 @@
 <article name="njs scripting language"
         link="/en/docs/njs/index.html"
         lang="en"
-        rev="33"
+        rev="34"
         toc="no">
 
 <section id="summary">
@@ -62,6 +62,10 @@ The compliance is still <link doc="compa
 </listitem>
 
 <listitem>
+<link doc="preload_objects.xml"/>
+</listitem>
+
+<listitem>
 <link id="tested_os_and_platforms">Tested OS and platforms</link>
 </listitem>
 
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/njs/preload_objects.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
+
+<article name="Understanding preloaded objects"
+        link="/en/docs/njs/preload_objects.html"
+        lang="en"
+        rev="1"
+        toc="no">
+
+<section id="summary">
+
+<para>
+For each incoming request njs creates a separate virtual machine.
+This brings a lot of benefits such as predictable memory consumption
+or requests isolation.
+</para>
+
+<para>
+However, it also has its own downsides.
+Since all requests are isolated,
+if a request handler needs to access some data,
+it has to read it by itself.
+This is not efficient especially when the amount of data is large.
+</para>
+
+<para>
+To address this limitation,
+a preloaded shared object was introduced.
+Such objects are created immutable and do not have prototype chains:
+their values cannot be changed, properties cannot be added or removed.
+</para>
+
+</section>
+
+
+<section id="working_with_preload_objects"
+       name="Working with preload objects">
+
+<para>
+Here are some examples of how to work with a preload object in njs:
+
+<list type="bullet">
+
+<listitem>
+access properties by name:
+<programlisting>
+preloaded_object.prop_name
+preloaded_object[prop_name]
+</programlisting>
+</listitem>
+
+<listitem>
+enumerate properties:
+<programlisting>
+for (i in preloaded_object_name) {
+    ...
+}
+</programlisting>
+</listitem>
+
+<listitem>
+apply non-modifying built-in methods using <literal>call()</literal>:
+<programlisting>
+Array.prototype.filter.call(preloaded_object_name, ...)
+</programlisting>
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+</article>
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -120,6 +120,7 @@ REFS =									\
 		njs/compatibility					\
 		njs/install						\
 		njs/node_modules					\
+		njs/preload_objects					\
 		njs/typescript						\
 
 TOP =									\
--- a/xml/ru/docs/njs/index.xml
+++ b/xml/ru/docs/njs/index.xml
@@ -9,7 +9,7 @@
 <article name="Сценарный язык njs"
         link="/ru/docs/njs/index.html"
         lang="ru"
-        rev="32"
+        rev="34"
         toc="no">
 
 <section id="summary">
@@ -22,8 +22,7 @@ njs совместим с
 (строгий режим) c некоторыми расширениями
 <link url="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript 6</link>
 и позже.
-Совместимость находится в стадии
-<link doc="compatibility.xml">развития</link>.
+Совместимость находится в стадии <link doc="compatibility.xml">развития</link>.
 </para>
 
 </section>
@@ -51,6 +50,10 @@ njs совместим с
 </listitem>
 
 <listitem>
+<link doc="security.xml"/>
+</listitem>
+
+<listitem>
 <link doc="compatibility.xml"/>
 </listitem>
 
@@ -59,6 +62,10 @@ njs совместим с
 </listitem>
 
 <listitem>
+<link doc="preload_objects.xml"/>
+</listitem>
+
+<listitem>
 <link id="tested_os_and_platforms">Протестированные ОС и платформы</link>
 </listitem>
 
new file mode 100644
--- /dev/null
+++ b/xml/ru/docs/njs/preload_objects.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
+
+<article name="Предзагруженные объекты"
+        link="/ru/docs/njs/preload_objects.html"
+        lang="ru"
+        rev="1"
+        toc="no">
+
+<section id="summary">
+
+<para>
+Для каждого входящего запроса в njs создаётся отдельная виртуальная машина.
+Это позволяет прогнозировать предсказуемое поглощение памяти
+или осуществить изоляцию запросов.
+</para>
+
+<para>
+Однако у такого подхода есть недостатки.
+Поскольку все запросы являются изолированными, то
+если обработчику запроса необходимо получить доступ к данным,
+ему нужно сначала их прочитать самому.
+Это неэффективно, особенно если объём данных большой.
+</para>
+
+<para>
+Это ограничение можно обойти
+при помощи разделяемого предзагруженного объекта.
+Такие объекты создаются неизменяемыми и не имеют цепочки прототипов:
+у них нет возможности
+изменить значения или добавить/удалить свойства в объектах/массивах.
+</para>
+
+</section>
+
+
+<section id="working_with_preload_objects"
+       name="Работа с предзагруженными объектами">
+
+<para>
+Примеры работы с предзагруженными объектами в njs:
+
+<list type="bullet">
+
+<listitem>
+доступ к свойствам по имени:
+<programlisting>
+preloaded_object.prop_name
+preloaded_object[prop_name]
+</programlisting>
+</listitem>
+
+<listitem>
+перечисление свойств:
+<programlisting>
+for (i in preloaded_object_name) {
+    ...
+}
+</programlisting>
+</listitem>
+
+<listitem>
+применение встроенных методов, не изменяющих состояние,
+при помощи <literal>call()</literal>:
+<programlisting>
+Array.prototype.filter.call(preloaded_object_name, ...)
+</programlisting>
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+</article>