Class: RingBuffer

RingBuffer(sab, type)

The base RingBuffer class A Single Producer - Single Consumer thread-safe wait-free ring buffer. The producer and the consumer can be on separate threads, but cannot change roles, except with external synchronization.

Constructor

new RingBuffer(sab, type)

Parameters:
Name Type Description
sab SharedArrayBuffer A SharedArrayBuffer obtained by calling RingBuffer.getStorageFromCapacity.
type TypedArray A typed array constructor, the type that this ring buffer will hold.
Source:

Classes

RingBuffer

Methods

availableRead()

Source:
Returns:
The number of elements available for reading. This can be late, and report less elements that is actually in the queue, when something has just been enqueued.

availableWrite()

Source:
Returns:
The number of elements available for writing. This can be late, and report less elements that is actually available for writing, when something has just been dequeued.

available_read()

Compatibility alias for availableRead().
Deprecated:
  • Yes
Source:
Returns:
The number of elements available for reading. This can be late, and report less elements that is actually in the queue, when something has just been enqueued.

available_write()

Compatibility alias for availableWrite.
Deprecated:
  • Yes
Source:
Returns:
The number of elements available for writing. This can be late, and report less elements that is actually available for writing, when something has just been dequeued.

capacity()

Source:
Returns:
The usable capacity for the ring buffer: the number of elements that can be stored.

empty()

Source:
Returns:
True if the ring buffer is empty false otherwise. This can be late on the reader side: it can return true even if something has just been pushed.

full()

Source:
Returns:
True if the ring buffer is full, false otherwise. This can be late on the write side: it can return true when something has just been popped.

pop(elements, length, offset)

Read up to `elements.length` elements from the ring buffer. `elements` is a typed array of the same type as passed in the ctor. Returns the number of elements read from the queue, they are placed at the beginning of the array passed as parameter.
Parameters:
Name Type Default Description
elements TypedArray An array in which the elements read from the queue will be written, starting at the beginning of the array.
length Number If passed, the maximum number of elements to pop. If not passed, up to elements.length are popped.
offset Number 0 If passed, an index in elements in which the data is written to. `elements.length - offset` must be greater or equal to `length`.
Source:
Returns:
The number of elements read from the queue.

push(elements, length, offset)

Push elements to the ring buffer.
Parameters:
Name Type Default Description
elements TypedArray A typed array of the same type as passed in the ctor, to be written to the queue.
length Number If passed, the maximum number of elements to push. If not passed, all elements in the input array are pushed.
offset Number 0 If passed, a starting index in elements from which the elements are read. If not passed, elements are read from index 0.
Source:
Returns:
the number of elements written to the queue.

type()

Source:
Returns:
the type of the underlying ArrayBuffer for this RingBuffer. This allows implementing crude type checking.

writeCallback(amount, cb)

Write bytes to the ring buffer using callbacks. This create wrapper objects and can GC, so it's best to no use this variant from a real-time thread such as an AudioWorklerProcessor `process` method. The callback is passed two typed arrays of the same type, to be filled. This allows skipping copies if the API that produces the data writes is passed arrays to write to, such as `AudioData.copyTo`.
Parameters:
Name Type Description
amount number The maximum number of elements to write to the ring buffer. If amount is more than the number of slots available for writing, then the number of slots available for writing will be made available: no overwriting of elements can happen.
cb function A callback with two parameters, that are two typed array of the correct type, in which the data need to be copied. If the callback doesn't return anything, it is assumed all the elements have been written to. Otherwise, it is assumed that the returned number is the number of elements that have been written to, and those elements have been written started at the beginning of the requested buffer space.
Source:
Returns:
The number of elements written to the queue.

writeCallbackWithOffset(amount, cb)

Write bytes to the ring buffer using a callback. This allows skipping copies if the API that produces the data writes is passed arrays to write to, such as `AudioData.copyTo`.
Parameters:
Name Type Description
amount number The maximum number of elements to write to the ring buffer. If amount is more than the number of slots available for writing, then the number of slots available for writing will be made available: no overwriting of elements can happen.
cb function A callback with five parameters: (1) The internal storage of the ring buffer as a typed array (2) An offset to start writing from (3) A number of elements to write at this offset (4) Another offset to start writing from (5) A number of elements to write at this second offset If the callback doesn't return anything, it is assumed all the elements have been written to. Otherwise, it is assumed that the returned number is the number of elements that have been written to, and those elements have been written started at the beginning of the requested buffer space.
Source:
Returns:
The number of elements written to the queue.

(static) getStorageForCapacity(capacity, type) → {SharedArrayBuffer}

Allocate the SharedArrayBuffer for a RingBuffer, based on the type and capacity required
Parameters:
Name Type Description
capacity number The number of elements the ring buffer will be able to hold.
type TypedArray A typed array constructor, the type that this ring buffer will hold.
Source:
Returns:
A SharedArrayBuffer of the right size.
Type
SharedArrayBuffer