ReadableStreamBYOBReader: метод read()

Метод read() интерфейса ReadableStreamBYOBReader используется для чтения данных в представление на буфере, предоставленном пользователем, из связанного потока байтов для чтения. Запрос данных будет удовлетворен из внутренних очередей потока, если такие данные присутствуют. Если очереди потока пусты, запрос может быть удовлетворен как передача без копирования из исходного байтового источника.

Метод принимает в качестве аргумента представление на буфере, в который должны быть считаны данные, и возвращает Promise. Обещание выполняется с объектом, имеющим свойства value и done, когда данные становятся доступны или если поток отменён. Если в потоке произошла ошибка, обещание будет отклонено с соответствующим объектом ошибки.

Когда блок данных предоставлен, свойство value будет содержать новое представление. Это будет представление над тем же буфером/поддерживающей памятью (и того же типа), что и исходное view , переданное методу read(), теперь заполненное новым блоком данных. Обратите внимание, что после выполнения обещания исходное view , переданное методу, будет отсоединено и больше не будет доступно. Обещание выполнится со значением value: undefined , если поток был отменён. В этом случае область поддерживающей памяти view удаляется и не возвращается вызывающей стороне (все ранее считанные данные в буфере представления теряются).

Свойство done указывает, ожидаются ли дополнительные данные. Значение устанавливается true , если поток закрыт или отменён, и false в противном случае.

Метод также имеет необязательный аргумент options.min, который можно использовать для указания минимального количества элементов, которые должны быть доступны, прежде чем обещание будет выполнено, пока поток активен. Представление, возвращённое в свойстве value , всегда будет содержать по крайней мере это количество элементов, за исключением случаев закрытия потока.

view

Представление, в которое должны быть считаны данные.

options Необязательно

Опции следующие:

min

Минимальное количество элементов для чтения, прежде чем обещание будет выполнено, пока поток активен. Если не указано, обещание будет выполнено с по крайней мере одним элементом, до максимального размера представления. Это число не должно быть больше представления, в которое производится чтение.

А Promise, который выполняется/отклоняется с результатом, в зависимости от состояния потока.

Возможны следующие варианты:

• Если блок данных доступен и поток всё ещё активен, обещание выполняется с объектом следующего формата:

  { value: theChunk, done: false }
  

  theChunk — представление, содержащее новые данные. Это представление того же типа и над той же поддерживающей памятью, что и view , переданное методу read(). Исходное view будет отсоединено и больше не будет доступно.

• Если поток закрыт, обещание выполняется с объектом следующего формата (где theChunk имеет те же свойства, что и выше):

  { value: theChunk, done: true }
  

• Если поток отменён, обещание выполняется с объектом следующего формата:

  { value: undefined, done: true }
  

  В этом случае поддерживающая память удаляется.

• Если в потоке возникает ошибка, обещание отклоняется с соответствующей ошибкой.

TypeError

Объект источника не является ReadableStreamBYOBReader, поток не имеет владельца, представление не является объектом или стало отсоединённым, длина представления равна 0, options.min равно 0 или вызывается ReadableStreamBYOBReader.releaseLock() (когда есть запрос на чтение).

RangeError

Значение options.min больше, чем представление, в которое производится запись.

Пример кода здесь взят из примеров в Использование потоков байтов для чтения.

Сначала мы создаём ридер с помощью ReadableStream.getReader() для потока, указывая mode: "byob" в параметре options. Нам также необходимо создать ArrayBuffer, который является "поддерживающей памятью" представлений, в которые мы будем записывать.

const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(4000);

Функция, использующая ридер, показана ниже. Она рекурсивно вызывает метод read() для чтения данных в буфер. Метод принимает Uint8Array массив типа данных, который является представлением части исходного буфера массива, который ещё не был заполнен. Параметры представления вычисляются из данных, полученных в предыдущих вызовах, которые определяют смещение в исходном буфере массива.

readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that fulfills when a value has been received
    reader
      .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
      .then(function processBytes({ done, value }) {
        // Result objects contain two properties:
        // done  - true if the stream has already given all its data.
        // value - some data. 'undefined' if the reader is canceled.

        if (done) {
          // There is no more data in the stream
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        // Read some more, and call this function again
        // Note that here we create a new view over the original buffer.
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
          .then(processBytes);
      });
  }
}

Когда в потоке больше нет данных, метод read() выполняется с объектом, в котором свойство done установлено в true, и функция возвращается.

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

Мы также сделали его примером в реальном времени. Обратите внимание, что большая часть кода не относится к примеру и поэтому скрыта. Для получения дополнительной информации см. Использование потоков байтов для чтения.

JavaScript

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  while (offset < buffer.byteLength) {
    // read() returns a promise that resolves when a value has been received
    reader
      .read(new Uint8Array(buffer, offset, buffer.byteLength - offset), {
        min: 101,
      })
      .then(async function processText({ done, value }) {
        // Result objects contain two properties:
        // done  - true if the stream has already given all its data.
        // value - some data. Always undefined when done is true.

        if (done) {
          logConsumer(
            `readStream() complete. Read ${value.byteLength} bytes (total: ${bytesReceived})`,
          );
          return;
        }

        buffer = value.buffer;
        offset += value.byteLength;
        bytesReceived += value.byteLength;

        //logConsumer(`Read ${bytesReceived} bytes: ${value}`);
        logConsumer(`Read ${value.byteLength} bytes (total: ${bytesReceived})`);
        result += value;

        // Read some more, and call this function again
        return reader
          .read(new Uint8Array(buffer, offset, buffer.byteLength - offset), {
            min: 101,
          })
          .then(processText);
      });
  }
}

Результат

Ниже показаны логирования из исходного потока (слева) и потребителя (справа). Обратите внимание, что если браузер поддерживает аргумент options.min , то каждый раз возвращается по крайней мере 101 элемент (и часто больше), за исключением случаев закрытия потока.

• ReadableStreamBYOBReader() конструктор
• Использование потоков байтов для чтения