7.13. Clara Pipeline FastIO Entry

FastIO entries are a representation of an allocated or not yet allocated shared memory segment, and provide the ability to manage shared memory data without user interaction if possible. FastIO input (or output) entries are generated when the first container in the pipeline tries to access an input (or output) in the pipeline definition of type array, string or any Clara Primitive (uint8, uint16, uint32, uint64, int8, int16, int32, int64, float16, float32, float64).

7.13.1. Pre-allocated FastIO Entries

FastIO entries are pre-allocated when their shape and element-type are well-defined in the pipeline definition (i.e. the shape contains no -1 or 0 in the entries, and the element-type is not a string).

The shape of preallocated FastIO entries in the operator payload cannot be updated, and any attempt to allocate the variable will result in an exception.

7.13.2. Dynamic-size FastIO Entries

FastIO entries do not have an allocation assigned when the shape and element-type are not well-defined: shape contains -1 or 0 in the pipeline definition, or element-type is a string.

The shape of a dynamic FastIO entry can be updated at runtime but only in the dimensions specified as “dynamic” (where shape contains a -1 or 0 in the pipeline definition). For example, if

shape = [3, -1, 224, -1]

that means that only shape[1] and shape[3] (the second and fourth entries when counting from zero) can be updated. If all the entries in the shape (after updates) are positive integers then the FastIO entry can be allocated.

7.13.3. Input- and Output-Type FastIO Entries

FastIO entries can be “input” and “output”.

  • Operators are given “read/write” access to FastIO output entries.
  • Operators are given “read-only” access FastIO input entries; this is to prevent dirty-reads or race conditions when one allocation is mapped as input to multiple operators. As a result one may never update values in a FastIO input entry.

7.13.3.1. FastIO Entry Accessors and Mutators

7.13.3.1.1. Name

Return

Returns the name of a clara.FastIOEntry.

type: str

@property
def name(self)

7.13.3.1.2. Is Pre-Allocated

Parameters

No parameters.

Return

Returns a boolean to indicate whether a clara.FastIOEntry was preallocated by the Clara Pipeline Driver (CPDriver).

type: str

@property
def is_preallocated(self)

7.13.3.1.3. Access

Parameters

No parameters.

Return

Returns a boolean to indicate whether a clara.FastIOEntry has an allocation in memory or not.

type: bool

@property
def is_allocated(self)

7.13.3.1.4. Access

Parameters

No parameters.

Return

Returns an enumeration (IOAccess.ReadOnly, IOAccess.ReadWrite) indicating the type of access to a clara.FastIOEntry.

type: IOAccess

@property
def access(self)

7.13.3.1.5. Shape

Parameters

No parameters.

Return

Returns the shape of a clara.FastIOEntry.

type: tuple

@property
def shape(self)

7.13.3.1.6. Element Type

Parameters

No parameters.

Return

Returns the element-type of a clara.FastIOEntry in the form of Numpy type.

type: numpy.dtype

@property
def element_type(self)

7.13.3.1.7. Dynamic Indices of the Shape

Parameters

No parameters.

Return

Returns the dynamic indices (if any) of a clara.FastIOEntry. These are the indices in the shape of a clara.FastIOEntry which contain a -1 in the pipeline definition.

type: tuple

@property
def dynamic_shape_indices(self)

Notes

  • Even after the shape attribute is updated this array will return the same indices; this is no indicate that at these dimensions in the array can be updated again at any point during runtime.

7.13.3.1.8. Is Dynamic

Parameters

No parameters.

Return

Returns a boolean to indicate whether a clara.FastIOEntry is dynamic or not. That is, if the shape attribute contains -1 or 0 entries in the pipeline definition.

type: bool

@property
def is_dynamic(self)

Notes

  • Implicitly, if is_dynamic returns True this also means that the shared memory allocation for this variable does not exist as the CPDriver does not know the actual size required.

7.13.3.1.9. Update Shape

Parameters

  • dimensions

    type: int list

    direction: In

    The indices of the shape of a clara.FastIOEntry to be updated.

  • new_values

    type: int list

    direction: In

    The values in the shape of a clara.FastIOEntry to update to.

Return

The updated shape of a clara.FastIOEntry.

type: tuple

def update_shape(self, dimensions: list, new_values: list)

Notes

  • update_shape will create a shared memory allocation for a clara.FastIOEntry if all the indices in its shape are positive integers.
  • Updates to non-dynamic indices in a clara.FastIOEntry will result those dimensions not being updated.

7.13.3.1.10. Get Values of Allocation as Read-Only Bytes

Parameters

No parameters.

Return

A read-only byte array representation of the values in a clara.FastIOEntry allocation.

type: bytes

def get_bytes(self)

Notes

  • If get_bytes is called before an allocation exists, as could be the case for dynamic arrays, a clara.Error is raised.

7.13.3.1.11. Get Values of Allocation as Numpy Array

Parameters

No parameters.

Return

A read-only numpy array representation of the values in a clara.FastIOEntry allocation.

type: numpy.ndarray

def get_numpy(self)

Notes

  • Any updates to the values of returned numpy array or its metadata (shape, ndtype, etc.) will **not* be reflected in the shaped memory allocation*, therefore downstream operators will not see any updates made to the numpy array returned by get_numpy.
  • If get_numpy is called before an allocation exists, as could be the case for dynamic arrays, a clara.Error is raised.

7.13.3.1.12. Set the Values in the Allocation

Parameters

  • new_values

    type: numpy.ndarray or buffer

    direction: In

    The new values to which to update the values in the allocation of a clara.FastIOEntry.

def set_values(self, new_vals)

Return

No return value.

** Notes **

  • If new_vals is a numpy.ndarray the element-type of the input array will be updated to that of the allocation of clara.FastIOEntry before the values are copied to the allocation.
  • If new_vals is a buffer no attempt is made to convert the values of the buffer, therefore if falls on the developer to perform any conversions necessary.