8.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).
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.
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.
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.
8.13.3.1.FastIO Entry Accessors and Mutators
8.13.3.1.1.Name
Return
Returns the name of a clara.FastIOEntry.
type: str
@property
def name(self)
8.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)
8.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)
8.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)
8.13.3.1.5.Shape
Parameters
No parameters.
Return
Returns the shape of a clara.FastIOEntry.
type: tuple
@property
def shape(self)
8.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)
8.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
shapeattribute 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.
8.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_dynamicreturnsTruethis also means that the shared memory allocation for this variable does not exist as the CPDriver does not know the actual size required.
8.13.3.1.9.Update Shape
Parameters
dimensions
type:
int listdirection: In
The indices of the shape of a
clara.FastIOEntryto be updated.new_values
type:
int listdirection: In
The values in the shape of a
clara.FastIOEntryto update to.
Return
The updated shape of a clara.FastIOEntry.
type: tuple
def update_shape(self, dimensions: list, new_values: list)
Notes
update_shapewill create a shared memory allocation for aclara.FastIOEntryif all the indices in itsshapeare positive integers.Updates to non-dynamic indices in a
clara.FastIOEntrywill result those dimensions not being updated.
8.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_bytesis called before an allocation exists, as could be the case for dynamic arrays, aclara.Erroris raised.
8.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 byget_numpy.If
get_numpyis called before an allocation exists, as could be the case for dynamic arrays, aclara.Erroris raised.
8.13.3.1.12.Set the Values in the Allocation
Parameters
new_values
type:
numpy.ndarrayorbufferdirection: 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_valsis anumpy.ndarraythe element-type of the input array will be updated to that of the allocation ofclara.FastIOEntrybefore the values are copied to the allocation.If
new_valsis abufferno attempt is made to convert the values of the buffer, therefore if falls on the developer to perform any conversions necessary.