pub trait VTable:
'static
+ Clone
+ Sized
+ Send
+ Sync
+ Debug {
type TypedArrayData: 'static + Send + Sync + Clone + Debug + Display + ArrayHash + ArrayEq;
type OperationsVTable: OperationsVTable<Self>;
type ValidityVTable: ValidityVTable<Self>;
Show 16 methods
// Required methods
fn id(&self) -> ArrayId;
fn validate(
&self,
data: &Self::TypedArrayData,
dtype: &DType,
len: usize,
slots: &[Option<ArrayRef>],
) -> VortexResult<()>;
fn nbuffers(array: ArrayView<'_, Self>) -> usize;
fn buffer(array: ArrayView<'_, Self>, idx: usize) -> BufferHandle;
fn buffer_name(array: ArrayView<'_, Self>, idx: usize) -> Option<String>;
fn with_buffers(
&self,
array: ArrayView<'_, Self>,
buffers: &[BufferHandle],
) -> VortexResult<ArrayParts<Self>>;
fn serialize(
array: ArrayView<'_, Self>,
session: &VortexSession,
) -> VortexResult<Option<Vec<u8>>>;
fn deserialize(
&self,
dtype: &DType,
len: usize,
metadata: &[u8],
buffers: &[BufferHandle],
children: &dyn ArrayChildren,
session: &VortexSession,
) -> VortexResult<ArrayParts<Self>>;
fn slot_name(array: ArrayView<'_, Self>, idx: usize) -> String;
fn execute(
array: Array<Self>,
ctx: &mut ExecutionCtx,
) -> VortexResult<ExecutionResult>;
// Provided methods
fn nchildren(array: ArrayView<'_, Self>) -> usize { ... }
fn child(array: ArrayView<'_, Self>, idx: usize) -> ArrayRef { ... }
fn child_name(array: ArrayView<'_, Self>, idx: usize) -> String { ... }
fn append_to_builder(
array: ArrayView<'_, Self>,
builder: &mut dyn ArrayBuilder,
ctx: &mut ExecutionCtx,
) -> VortexResult<()> { ... }
fn reduce(array: ArrayView<'_, Self>) -> VortexResult<Option<ArrayRef>> { ... }
fn reduce_parent(
array: ArrayView<'_, Self>,
parent: &ArrayRef,
child_idx: usize,
) -> VortexResult<Option<ArrayRef>> { ... }
}Expand description
The array VTable encapsulates logic for an Array type within Vortex.
The logic is split across several “VTable” traits to enable easier code organization than simply lumping everything into a single trait.
From this VTable trait, we derive implementations for the sealed DynArrayData trait and the
public ArrayPlugin registry trait.
The functions defined in these vtable traits will typically document their pre- and
post-conditions. The pre-conditions are validated inside the DynArrayData and ArrayRef
implementations so do not need to be checked in the vtable implementations (for example, index
out of bounds). Post-conditions are validated after invocation of the vtable function and will
panic if violated.
Required Associated Types§
Sourcetype TypedArrayData: 'static + Send + Sync + Clone + Debug + Display + ArrayHash + ArrayEq
type TypedArrayData: 'static + Send + Sync + Clone + Debug + Display + ArrayHash + ArrayEq
Per-array data owned by this encoding, excluding child arrays.
Child arrays belong in ArrayParts::slots so traversal,
serialization, and layout writers can discover them generically.
Sourcetype OperationsVTable: OperationsVTable<Self>
type OperationsVTable: OperationsVTable<Self>
Scalar and element-wise operation hooks for this encoding.
Sourcetype ValidityVTable: ValidityVTable<Self>
type ValidityVTable: ValidityVTable<Self>
Validity hook for nullable instances of this encoding.
Required Methods§
Sourcefn validate(
&self,
data: &Self::TypedArrayData,
dtype: &DType,
len: usize,
slots: &[Option<ArrayRef>],
) -> VortexResult<()>
fn validate( &self, data: &Self::TypedArrayData, dtype: &DType, len: usize, slots: &[Option<ArrayRef>], ) -> VortexResult<()>
Validates that externally supplied logical metadata matches the array data.
This is called by Array::try_from_parts before the array
is published. Implementations should check dtype, length, slot count, child dtypes/lengths,
metadata bounds, and any buffer shape invariants that unsafe accessors depend on.
Sourcefn nbuffers(array: ArrayView<'_, Self>) -> usize
fn nbuffers(array: ArrayView<'_, Self>) -> usize
Returns the number of top-level buffers in the array.
Sourcefn buffer(array: ArrayView<'_, Self>, idx: usize) -> BufferHandle
fn buffer(array: ArrayView<'_, Self>, idx: usize) -> BufferHandle
Sourcefn buffer_name(array: ArrayView<'_, Self>, idx: usize) -> Option<String>
fn buffer_name(array: ArrayView<'_, Self>, idx: usize) -> Option<String>
Returns the name of the buffer at the given index, or None if unnamed.
Sourcefn with_buffers(
&self,
array: ArrayView<'_, Self>,
buffers: &[BufferHandle],
) -> VortexResult<ArrayParts<Self>>
fn with_buffers( &self, array: ArrayView<'_, Self>, buffers: &[BufferHandle], ) -> VortexResult<ArrayParts<Self>>
Rebuild this array with replacement top-level buffers.
This is for physical rewrites that preserve dtype, len, child slots, buffer count, and
buffer lengths. The caller checks the generic invariants before dispatching here;
implementations should interpret the replacement buffers for their encoding-specific
in-memory representation.
Sourcefn serialize(
array: ArrayView<'_, Self>,
session: &VortexSession,
) -> VortexResult<Option<Vec<u8>>>
fn serialize( array: ArrayView<'_, Self>, session: &VortexSession, ) -> VortexResult<Option<Vec<u8>>>
Sourcefn deserialize(
&self,
dtype: &DType,
len: usize,
metadata: &[u8],
buffers: &[BufferHandle],
children: &dyn ArrayChildren,
session: &VortexSession,
) -> VortexResult<ArrayParts<Self>>
fn deserialize( &self, dtype: &DType, len: usize, metadata: &[u8], buffers: &[BufferHandle], children: &dyn ArrayChildren, session: &VortexSession, ) -> VortexResult<ArrayParts<Self>>
Deserialize an array from serialized metadata, buffers, and children.
The returned ArrayParts are still validated by the generic adapter.
Deserializers should use the provided session to resolve plugin-owned metadata instead of
relying on global state.
Sourcefn execute(
array: Array<Self>,
ctx: &mut ExecutionCtx,
) -> VortexResult<ExecutionResult>
fn execute( array: Array<Self>, ctx: &mut ExecutionCtx, ) -> VortexResult<ExecutionResult>
Execute this array by returning an ExecutionResult.
Execution is iterative, not recursive. Instead of recursively executing children,
implementations should return ExecutionResult::execute_slot to request that the
scheduler execute a slot first, or ExecutionResult::done when the encoding can
produce a result directly.
For good examples of this pattern, see:
Dict::execute— demonstrates requiring children viarequire_child!and producing a result once they are canonical.BitPacked::execute(invortex-fastlanes) — demonstrates requiring patches and validity viarequire_patches!/require_validity!.
Array execution is designed such that repeated execution of an array will eventually converge to a canonical representation. Implementations of this function should therefore ensure they make progress towards that goal.
The returned array (in Done) must be logically equivalent to the input array. In other
words, the recursively canonicalized forms of both arrays must be equal.
Debug builds will panic if the returned array is of the wrong type, wrong length, or incorrectly contains null values.
Provided Methods§
Sourcefn nchildren(array: ArrayView<'_, Self>) -> usize
fn nchildren(array: ArrayView<'_, Self>) -> usize
Returns the number of children in the array.
The default counts non-None slots.
Sourcefn child(array: ArrayView<'_, Self>, idx: usize) -> ArrayRef
fn child(array: ArrayView<'_, Self>, idx: usize) -> ArrayRef
Returns the child at the given index.
The default returns the idx-th non-None slot.
§Panics
Panics if idx >= nchildren(array).
Sourcefn child_name(array: ArrayView<'_, Self>, idx: usize) -> String
fn child_name(array: ArrayView<'_, Self>, idx: usize) -> String
Returns the name of the child at the given index.
The default returns the slot name of the idx-th non-None slot.
§Panics
Panics if idx >= nchildren(array).
Sourcefn append_to_builder(
array: ArrayView<'_, Self>,
builder: &mut dyn ArrayBuilder,
ctx: &mut ExecutionCtx,
) -> VortexResult<()>
fn append_to_builder( array: ArrayView<'_, Self>, builder: &mut dyn ArrayBuilder, ctx: &mut ExecutionCtx, ) -> VortexResult<()>
Writes the array’s logical values into a canonical builder.
The default implementation executes the full array to Canonical and appends that result.
Encodings may override this to avoid materializing an intermediate canonical array.
Sourcefn reduce(array: ArrayView<'_, Self>) -> VortexResult<Option<ArrayRef>>
fn reduce(array: ArrayView<'_, Self>) -> VortexResult<Option<ArrayRef>>
Attempt to reduce the array to a simpler representation without changing logical values.
Reductions are opportunistic and may return Ok(None) when no cheaper representation is
known.
Sourcefn reduce_parent(
array: ArrayView<'_, Self>,
parent: &ArrayRef,
child_idx: usize,
) -> VortexResult<Option<ArrayRef>>
fn reduce_parent( array: ArrayView<'_, Self>, parent: &ArrayRef, child_idx: usize, ) -> VortexResult<Option<ArrayRef>>
Attempt to reduce parent after this array appears as one of its children.
This is used by lazy arrays to let child execution unlock parent simplifications.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".