Пространство имён zone

Содержание

• Введение
  • Несколько рабочих против нескольких зон
  • Типы зон
  • Операции с зонами
• API
  • create(id: string, settings: ZoneSettings = DEFAULT_SETTINGS): Zone
  • get(id: string): Zone
  • current: Zone
  • node: Zone
  • Интерфейс ZoneSettings
    • settings.workers: number
  • Объект DEFAULT_SETTINGS: ZoneSettings
  • Интерфейс Zone
    • zone.id: string
    • zone.broadcast(code: string): Promise<void>
    • zone.broadcast(function: (...args: any[]) => void, args?: any[]): Promise<void>
    • zone.execute(moduleName: string, functionName: string, args?: any[], options?: CallOptions): Promise<Result>
    • zone.execute(function: (...args[]) => any, args?: any[], options?: CallOptions): Promise<Result>
  • Интерфейс CallOptions
    • options.timeout: number
  • Интерфейс Result
    • result.value: any
    • result.payload: string
    • result.transportContext: transport.TransportContext

Введение

Zone — это ключевая концепция napajs, которая предоставляет возможности многопоточности в мире JavaScript и представляет собой логическую группу симметричных рабочих процессов для выполнения определённых задач.

Обратите внимание, что это не то же самое понятие зоны, как контекстный объект для асинхронных вызовов в Dart, Angular или предложение в TC39.

Несколько рабочих против нескольких зон

Зона состоит из одного или нескольких потоков JavaScript, каждый поток мы называем worker. Рабочие внутри зоны симметричны, это означает, что код, выполняемый на любом рабочем из зоны, должен возвращать один и тот же результат, а внутреннее состояние каждого рабочего должно быть одинаковым с точки зрения долгосрочного использования.

В одном процессе могут сосуществовать несколько зон, каждая из которых загружает разный код, имеет разное состояние или применяет разные политики, такие как размер кучи и т. д. Цель наличия нескольких зон — позволить выполнять различные роли для сложных задач, при этом каждая роль загружает минимум ресурсов для своего использования.

Типы зон

Существует два типа зон:

• Napa zone — зона состоит из управляемых Napa.js рабочих процессов JavaScript (V8 isolates). Может быть несколько, каждая может содержать несколько рабочих. Рабочие в зоне Napa поддерживают частичные API Node.JS.
• Node zone — «виртуальная» зона, предоставляющая доступ к циклу событий Node.js, имеющая доступ ко всем возможностям Node.js.

Операции с зонами

Существуют две операции, предназначенные для усиления симметрии рабочих внутри зоны:

1. Broadcast — выполнение кода, который изменяет состояние рабочего на всех рабочих, возвращая обещание для ожидающей операции. Через обещание мы можем только узнать, успешно ли выполнена операция или нет. Обычно мы используем broadcast для начальной загрузки приложения, предварительного кэширования объектов или изменения настроек приложения. Также предлагается функция broadcastSync как синхронизированная версия операций broadcast.
2. Execute — выполнение кода, который не изменяет состояние рабочего процесса на произвольном рабочем, возвращая обещание получения результата. Execute предназначен для реальной работы.

Операции с зоной выполняются по принципу «первым пришёл — первым обслужен», при этом broadcast имеет более высокий приоритет над execute. Создание зоны с использованием библиотеки napajs

var napa = require('napajs');
var zone1 = napa.zone.create('zone1');

Пример 2: Создание зоны с идентификатором 'zone2', с 1 рабочим.

var zone2 = napa.zone.create('zone2', {
    workers: 1
});

get(id: string): Zone

Получает ссылку на зону по идентификатору. Если зона не существует, будет выброшено исключение.

Пример:

var zone = napa.zone.get('zone1');

current: Zone

Возвращает ссылку на зону текущего запущенного изолятора. Если это в среде node, то возвращает зону узла.

Пример: Получить текущую зону.

var zone = napa.zone.current;

node: Zone

Возвращает ссылку на зону узла. Это эквивалентно napa.zone.get('node').

Пример:

var zone = napa.zone.node;

Интерфейc ZoneSettings

Настройки для зон, которые будут указаны при создании зон. Если не указано, будут использоваться DEFAULT_SETTINGS.

settings.workers: number

Количество рабочих в зоне.

Объект DEFAULT_SETTINGS

Значения по умолчанию для создания зон.

{
    workers: 2
}

Интерфейс Zone

Зона — это базовая концепция для выполнения JavaScript и применения политик в Napa. Вы можете найти его определение в Введение. Через API зоны разработчики могут транслировать код JavaScript на всех рабочих или выполнять функцию на одном из них. При программировании против зоны лучше всего обеспечить, чтобы все рабочие в зоне были симметричны друг другу, то есть вы не должны предполагать, что рабочий может поддерживать свои собственные состояния.

Два основных набора API — broadcast и execute, которые являются асинхронными операциями с несколькими вариантами ввода.

zone.id: string

Получение идентификатора зоны.

broadcast(code: string): Promise

Асинхронная трансляция фрагмента кода JavaScript в виде строки всем рабочим, которая возвращает Promise типа void. Если какой-либо из рабочих не смог выполнить код, обещание будет отклонено с сообщением об ошибке.

Пример:

var napa = require('napajs');
var zone = napa.zone.get('zone1');
zone.broadcast('var state = 0;')
    .then(() => {
        console.log('трансляция прошла успешно.');
    })
    .catch((error) => {
        console.log('трансляция не удалась.')
    });

broadcastSync(code: string): void

Синхронная трансляция фрагмента кода JavaScript в виде строки всем рабочим. Если какой-либо из рабочих не сможет выполнить код, будет выдано исключение с сообщением об ошибке.

Примечания:

• Не разрешено вызывать broadcastSync в текущей зоне. Это вызовет тупик.

Пример:

var napa = require('napajs');
var zone = napa.zone.get('zone1');
try {
    zone.broadcastSync('var state = 0;');
    console.log('трансляция прошла успешно.');
} catch (error) {
    console.log('трансляция не удалась.')
}

broadcast(function: (...args: any[]) => void | Promise, args?: any[]): Promise

Асинхронная трансляция анонимной функции с аргументами всем рабочим, которая возвращает Promise типа void. Если какой-либо из рабочих не сможет выполнить код, обещание будет отклонено с сообщением об ошибке.

Примечания:

• Если функция возвращает объект Promise, его состояние будет принято возвращаемым значением broadcast.
• Объект функции не может получить доступ к переменным из замыкания.
• Если у объекта функции нет свойства origin, он будет использовать текущий файл как origin, который будет использоваться для установки __filename и __dirname. (См. транспорт функций)
• Транспортный контекст недоступен в трансляции. Все типы, зависящие от TransportContext (например, TransportError), будут преобразованы в обычные ошибки JavaScript. zone.broadcast((state) => { require('some-module').setModuleState(state) }, [{field1: 1}]) .then(() => { console.log('broadcast succeeded.'); }) .catch((error) => { console.log('broadcast failed:', error) });

zone.broadcastSync(function: (...args: any[]) => void | Promise<void>, args?: any[]): void

Синхронно транслирует анонимную функцию с аргументами всем воркерам. Если какой-либо из воркеров не смог выполнить код, будет выброшено исключение с сообщением об ошибке.

Примечания:

• Не допускается вызывать broadcastSync в текущей зоне. Это приведёт к тупиковой ситуации.
• Если функция возвращает объект Promise, его состояние будет принято. Функция broadcastSync не вернётся, пока этот Promise не будет разрешён или отклонён.
• Объект функции не может получить доступ к переменным из замыкания.
• Если у объекта функции нет свойства origin, он будет использовать текущий файл как origin, который будет использоваться для установки __filename и __dirname (см. «Транспортировка функций»).
• Контекст транспортировки недоступен в трансляции. Все типы, зависящие от TransportContext (например, ShareableWrap, Transportable), не могут быть переданы в списке аргументов.

Пример:

try {
    zone.broadcastSync((state) => {
            require('some-module').setModuleState(state)
        }, [{field1: 1}]);
    console.log('broadcast succeeded.');
} catch (error) {
    console.log('broadcast failed:', error)
}

zone.execute(moduleName: string, functionName: string, args?: any[], options?: CallOptions): Promise<any>

Выполняет функцию асинхронно на произвольном воркере через имя модуля и имя функции. Аргументы могут быть любого типа JavaScript, который можно транспортировать. Возвращает Promise объекта Result. Если произойдёт ошибка, либо плохой код, пользовательское исключение или достигнут тайм-аут, обещание будет отклонено.

Пример: Выполнить функцию bar в модуле foo с аргументами [1, «hello», { field1: 1 }]. Применяется тайм-аут 300 мс.

zone.execute(
    'foo', 
    'bar', 
    [1, "hello", {field1: 1}], 
    { timeout: 300 })
    .then((result) => {
        console.log('execute succeeded:', result.value);
    })
    .catch((error) => {
        console.log('execute failed:', error);
    });

zone.execute(function: (...args: any[]) => any, args?: any[], options?: CallOptions): Promise<any>

Выполнить объект функции асинхронно на произвольном работнике. Аргументы могут быть любого типа JavaScript, который можно транспортировать. Возвращается Promise объекта Result. Если произойдёт ошибка, либо плохой код, пользовательское исключение или тайм-аут достигнут, обещание будет отклонено.

Примечания:

• Если функция возвращает Promise, он будет принят.
• Объект функции не может получить доступ к переменным из замыкания.
• Если объект функции не имеет свойства origin, он будет использовать текущий файл в качестве origin, который будет использоваться для установки __filename и __dirname.

Пример:

zone.execute((a: number, b: string, c: object) => {
        return a + b + JSON.stringify(c);
    }, [1, "hello", {field1: 1}])
    .then((result) => {
        console.log('execute succeeded:', result.value);
    })
    .catch((error) => {
        console.log('execute failed:', error);
    });

Вывод:

execute succeeded: 1hello{"field1":1}
``` ## Выполнение zone.execute(() => { console.log(__filename);});

Вывод:

/usr/file1.js
## 

Интерфейс `CallOptions`

Интерфейс для опций вызова функций в `zone.execute`.

### options.timeout: number
Время ожидания в миллисекундах. Значение по умолчанию 0 указывает на отсутствие времени ожидания.

## Результат

Интерфейс `Result`

Интерфейс доступа к возвращаемому значению из [`execute`](#execute-by-name).

### result.value: any
Значение JavaScript, возвращённое функцией, которая вызывается из zone.execute/executeSync. Napa выполняет маршаллинг/унмаршаллинг [переносимых значений](transport.md#transportable-types) между разными воркерами (V8 isolates). Унмаршаллинг происходит при первом запросе `result.value`.
Пример:
```js
var value = result.value;

result.payload: string

Маршалированная полезная нагрузка (в формате JSON) из возвращённого значения. Это поле предназначено для пользователей, которые хотят передать результаты своему вызывающему объекту, где не требуется размаршалированное значение.

Пример:

var payload = result.payload;

result.transportContext: transport.TransportContext

TransportContext, который необходим для унмаршаллинга result.payload в result.value.

Пример:

var napa = require('napajs');
var zone = napa.zone.create('zone1');
zone.execute(() => { return 0; }, [])
    .then((result) => {
        // Ручной маршаллинг.
        var transportContext = result.transportContext;
        var value = napa.transport.unmarshall(result.payload, result.transportContext);

        // result.value и ручной размаршаллинг из полезной нагрузки совпадают.
        assert.equal(value, result.value);
    });