Dolphin Bufferizer

class dolphin.Bufferizer(shape: tuple, buffer_size: int, dtype: dtype, stream: Optional[pycuda.driver.Stream] = None, flush_hook: Optional[callable] = None, allocate_hook: Optional[callable] = None, append_one_hook: Optional[callable] = None, append_multiple_hook: Optional[callable] = None, buffer_full_hook: Optional[callable] = None)

Bases: object

Bufferizer is a class that allows to easily bufferize data on the GPU. The purpose is to handle seamlessly batched data and to avoid unnecessary memory allocation but rather reuse the same memory buffer and favour copy operations.

Bufferizer can, through its append methods, append data to the buffer. It can be either one darray at a time, a list of darray`s or a single batched `darray.

In addition to bufferizing data, the class also allows to trigger hooks at different moments of its lifecycle.

• flush_hook : callable triggered when buffer is flushed

• allocate_hook : callable triggered when buffer is allocated

• append_one_hook : callable triggered when buffer has a new element appended

• append_multiple_hook : callable triggered when buffer has new elements appended

• buffer_full_hook : callable triggered when the buffer is full after calling any append

Parameters:

• shape (tuple) – shape of element to bufferize

• buffer_size (int) – size of the buffer

• dtype (dolphin.dtype) – dtype of the element to bufferize

• stream (cuda.Stream, optional) – stream to use for the buffer, defaults to None

• flush_hook (callable, optional) – callable triggered when buffer is flushed, defaults to None

• allocate_hook (callable, optional) – callable triggered when buffer is allocated, not triggered by the first allocation, defaults to None

• append_one_hook (callable, optional) – callable triggered when buffer has a new element appended, defaults to None

• append_multiple_hook (callable, optional) – callable triggered when buffer has new elements appended, defaults to None

• buffer_full_hook (callable, optional) – callable triggered when the buffer is full after calling any append, defaults to None

__init__(shape: tuple, buffer_size: int, dtype: dtype, stream: Optional[pycuda.driver.Stream] = None, flush_hook: Optional[callable] = None, allocate_hook: Optional[callable] = None, append_one_hook: Optional[callable] = None, append_multiple_hook: Optional[callable] = None, buffer_full_hook: Optional[callable] = None)

Constructor of the Bufferizer class.

allocate() → None

Method to allocate the buffer on the GPU. This method is called automatically when the class is instanciated.

Once the buffer is allocated, it is not possible to change the size and it the allocation is initialized to 0.

Also, this methods triggers the allocate_hook if it is not None.

append(element: Union[darray, List[darray]]) → None

General purpose append method. You can provide either a single darray, a batched darray or a list of darray and the method will handle it.

For more details about the handling of each case, see the append_one and append_multiple methods.

Parameters:

element (Union[dolphin.darray, List[dolphin.darray]]) – The element to append to the buffer.

append_one(element: darray) → None

Method to append one element to the buffer. The element is copied and appended to the buffer. element must be a darray of the same shape and dtype as the bufferizer. The size of the buffer is increased by one.

Appending one element triggers the append_one_hook if it is not None. Once the buffer is full, the buffer_full_hook is triggered.

Parameters:

element (dolphin.darray) – The element to append to the buffer.

append_multiple(element: Union[darray, List[darray]]) → None

Function used in order to append multiple darray to the buffer at once. The darray must be of the same shape and dtype as the bufferizer with the exception of the first dimension which can be different in case of a batched darray. Otherwise, the darray must be a list of darray of the same shape and dtype as the bufferizer.

The size of the buffer is increased by the number of elements in element.

It is assumed that the number of elements in element is defined as the first dimension of its shape. For instance:

element.shape = (batch_size, *self._shape)

Appending multiple elements triggers the append_multiple_hook if it is not None. Once the buffer is full, the buffer_full_hook is triggered if it is not None.

Parameters:

element (darray) – The element to append to the buffer.

flush(value: Any = 0) → None

Set the buffer to a given value. Useful in order to get rid of any residual data in the buffer.

Calling this method triggers the flush_hook if it is not None.

Parameters:

stream (cuda.Stream, optional) – Cuda stream, defaults to None

flush_hook(hook: callable)

Method to set the flush hook. This hook is called when the flush method is called.

Parameters:

hook (callable) – Callable function called each time the flush method is called.

allocate_hook(hook: callable)

Method to set the allocate hook. This hook is called when the allocate method is called.

Parameters:

hook (callable) – Callable function called each time the allocate method is called.

append_one_hook(hook: callable)

Method to set the append one hook.

Parameters:

hook (callable) – Callable function called each time the append_one method is called.

append_multiple_hook(hook: callable)

Method to set the append multiple hook.

Parameters:

hook (callable) – Callable function called each time the append_multiple method is called.

buffer_full_hook(hook: callable)

Method to set the buffer full hook.

Parameters:

hook (callable) – Callable function called each time the buffer is full.

property allocation: pycuda.driver.DeviceAllocation

Property in order to get the allocation of the buffer.

Returns:

Allocation of the buffer.

Return type:

cuda.DeviceAllocation

property darray: darray

Property in order to convert a bufferizer to a darray.

Important note : The darray returned by this property is not a copy of the bufferizer. It is a view of the bufferizer. Any change to the darray will be reflected in the bufferizer and vice-versa.

Returns:

darray of bufferizer

Return type:

dolphin.darray

property element_nbytes: int

Property in order to get the number of bytes of a single element in the buffer.

Returns:

Number of bytes of a single element in the buffer.

Return type:

int

property nbytes: int

Property in order to get the number of bytes of the buffer.

Returns:

Number of bytes of the buffer.

Return type:

int

__module__ = 'dolphin.core.bufferizer'

property full: bool

Property in order to know if the buffer is full.

Returns:

True if the buffer is full, False otherwise.

Return type:

bool

property shape: tuple

Property in order to get the shape of the the buffer.

Returns:

Shape of the buffer.

Return type:

tuple

property element_shape: tuple

Property in order to get the shape of a single element in the buffer.

Returns:

Shape of a single element in the buffer.

Return type:

tuple

property dtype: dtype

Property in order to get the dtype of the buffer.

Returns:

Dtype of the buffer.

Return type:

dolphin.dtype

__len__() → int

Method in order to get the number of elements in the buffer.

Returns:

Number of elements in the buffer.

Return type:

int