Node.js — Документация

Содержание

Потоки

Поток — это абстрактный интерфейс, реализуемый многими объектами в Node. Например, запрос к HTTP-серверу является потоком, также как stdout. Потоки могут быть с возможностью чтения, записи или и того и другого. Все потоки являются экземплярами EventEmitter.

Поток с возможностью чтения

Поток с возможностью чтения имеет следующие методы, свойства и события.

Event: 'data'

function (data) { }

Событие 'data' передаёт обработчику либо Buffer (по умолчанию), либо строку, если предварительно был вызван setEncoding().

Event: 'end'

function () { }

Генерируется когда поток получает символ конца файла EOF (FIN в терминологии TCP). Означает что событий 'data' больше не предвидится. Если поток также имеет возможность записи, писать данные можно и дальше.

Event: 'error'

function (exception) { }

Генерируется если при приёме данных произошла ошибка.

Event: 'close'

function () { }

Генерируется когда соответствующий потоку файловый дескриптор закрывается. Не все потоки генерируют это событие. Например, входящий HTTP запрос не генерирует 'close'.

Event: 'fd'

function (fd) { }

Генерируется когда поток получает файловый дескриптор. Только UNIX потоки поддерживают этот функционал; остальные никогда не генерируют это событие.

stream.readable

A boolean that is true by default, but turns false after an 'error' occured, the stream came to an 'end', or destroy() was called.

stream.setEncoding(encoding)

Заставляет событие 'data' передавать обработчику строку вместо буфера. encoding может быть 'utf8', 'ascii' или 'base64'.

stream.pause()

Прекращает поступление событий 'data'.

stream.resume()

Возобновляет поступление событий 'data' после pause().

stream.destroy()

Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.

stream.pipe(destination, [options])

Соединяет поток с возможностью чтения с потоком destination, доступным для записи. Все читаемые этим поток данные будут записаны в destination. Для синхронизации вшуюсяпотоков можно использовать stream.pause() и stream.resume().

Пример эмуляции UNIX-команды cat:

process.stdin.resume();
process.stdin.pipe(process.stdout);

По умолчанию при поступлдении события end у источника будет вызван метод end() у приёмника destination is no longer writable. Если в качестве options передать { end: false }, то поток-приёмник останется открытым после закрытия потока-источника:

process.stdin.resume();

process.stdin.pipe(process.stdout, { end: false });

process.stdin.on("end", function() {
  process.stdout.write("Goodbye\n");
});

ПРИМЕЧАНИЕ: Если поток-источник не поддерживает pause() и resume(), эта функция одобалвяет в объект простую реализацию этих функцйи, вызывающую события 'pause' и 'resume', соответственно.

Поток с возможностью записи

У потока с возможностью записи есть следующие методы, свойства и события.

Event: 'drain'

function () { }

Генерируется после вызова метода write() вернувшего false — сигнал о том, что можно писать дальше.

Event: 'error'

function (exception) { }

Генерируется при ошибке с исключением exception.

Event: 'close'

function () { }

Генерируется когда закрывается соответствующий потоку дескриптор.

stream.writable

Булево свойство, по умолчанию true, но становящиеся false после наступления события 'error' или вызова end() / destroy().

stream.write(string, encoding='utf8', [fd])

Записывает строку string в указанной кодировке encoding в поток. Возвращает true если строка попала в буфер ядра. Возвращает false если буфер ядра полон и данные будут отправлены позже. Когда данные будут отправлены и буфер ядра опустеет, будет сгенерировано событие 'drain'. Кодировка по умолчанию — 'utf8'.

Если указан необязательный параметр fd, он интерпретируется как файловый дескриптор для отправки в поток. Это поддерживается только в UNIX потоках, и просто игнорируется в другом окружении. Когда дескриптор пересылается таким образом, если он будет закрыт до события 'drain' потока, может быть отправлен повреждённый (закрытый) дескриптор.

stream.write(buffer)

То же что и выше, но с использованием буфера.

stream.end()

Закрывает поток отправкой EOF или FIN.

stream.end(string, encoding)

Посылает строку string в указанной кодировке encoding и закрывает поток отправкой EOF или FIN. Так можно уменьшить общее число отправленных пакетов.

stream.end(buffer)

То же что выше но с использованием буфера.

stream.destroy()

Закрывает соответствующий потоку файловый дескриптор. Поток больше не будет генерировать событий.

stream.destroySoon()

Закрывает соответствующий потоку файловый дескриптор после того, как очередь записи окажется пустой.