Skip to main content

ObjectBlockOps

kvbm_engine::object

Trait ObjectBlockOps 

Source 
pub trait ObjectBlockOps: Send + Sync {
    // Required methods
    fn has_blocks(
        &self,
        keys: Vec<SequenceHash>,
    ) -> BoxFuture<'static, Vec<(SequenceHash, Option<usize>)>>;
    fn put_blocks(
        &self,
        keys: Vec<SequenceHash>,
        src_layout: LogicalLayoutHandle,
        block_ids: Vec<BlockId>,
    ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>;
    fn get_blocks(
        &self,
        keys: Vec<SequenceHash>,
        dst_layout: LogicalLayoutHandle,
        block_ids: Vec<BlockId>,
    ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>;

    // Provided methods
    fn put_blocks_with_layout(
        &self,
        keys: Vec<SequenceHash>,
        _layout: PhysicalLayout,
        _block_ids: Vec<BlockId>,
    ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>> { ... }
    fn get_blocks_with_layout(
        &self,
        keys: Vec<SequenceHash>,
        _layout: PhysicalLayout,
        _block_ids: Vec<BlockId>,
    ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>> { ... }
}
Expand description

Unified object block operations trait.

This trait provides high-level operations for storing and retrieving KV cache blocks in object storage (e.g., S3, MinIO).

Uses LogicalLayoutHandle to identify source/destination layouts. In distributed mode, workers resolve the logical handle to their own physical layouts. This allows the leader (which doesn’t have physical layouts) to use the same trait.

Uses 'static BoxFuture for runtime flexibility - implementations clone/Arc what they need from self. Takes owned Vecs for simplicity; keys are returned in results so callers can correlate success/failure.

Implemented by:

  • S3ObjectBlockClient - direct S3 operations (has_blocks only; put/get require physical layout)
  • DirectWorker - resolves logical handle to physical layout, then delegates
  • CoordinatedWorker - delegates to inner worker
  • LeaderObjectClient - coordinates workers for distributed uploads

Required Methods§

Source

fn has_blocks( &self, keys: Vec<SequenceHash>, ) -> BoxFuture<'static, Vec<(SequenceHash, Option<usize>)>>

Check if blocks exist in object storage.

Returns a vector of (hash, size_option) pairs where:

  • Some(size) indicates the block exists with the given size in bytes
  • None indicates the block does not exist or an error occurred
Source

fn put_blocks( &self, keys: Vec<SequenceHash>, src_layout: LogicalLayoutHandle, block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Put blocks to object storage.

§Arguments
  • keys - Sequence hashes identifying each block
  • src_layout - Logical layout handle identifying the source (workers resolve to physical)
  • block_ids - Block IDs within the layout to upload

Returns a vector of results for each block:

  • Ok(hash) indicates the block was successfully stored
  • Err(hash) indicates the block failed to store
§Note

For S3ObjectBlockClient, this will error - use put_blocks_with_layout instead. Workers should resolve the logical handle to their physical layout first.

Source

fn get_blocks( &self, keys: Vec<SequenceHash>, dst_layout: LogicalLayoutHandle, block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Get blocks from object storage.

§Arguments
  • keys - Sequence hashes identifying each block
  • dst_layout - Logical layout handle identifying the destination (workers resolve to physical)
  • block_ids - Block IDs within the layout to download into

Returns a vector of results for each block:

  • Ok(hash) indicates the block was successfully retrieved
  • Err(hash) indicates the block failed to retrieve
§Note

For S3ObjectBlockClient, this will error - use get_blocks_with_layout instead. Workers should resolve the logical handle to their physical layout first.

Provided Methods§

Source

fn put_blocks_with_layout( &self, keys: Vec<SequenceHash>, _layout: PhysicalLayout, _block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Put blocks to object storage using a resolved physical layout.

This method is called by workers after resolving a logical handle to their physical layout. The default implementation errors; storage backends like S3ObjectBlockClient override this with actual upload logic.

§Arguments
  • keys - Sequence hashes identifying each block
  • layout - Physical layout containing the block data
  • block_ids - Block IDs within the layout to upload
Source

fn get_blocks_with_layout( &self, keys: Vec<SequenceHash>, _layout: PhysicalLayout, _block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Get blocks from object storage into a resolved physical layout.

This method is called by workers after resolving a logical handle to their physical layout. The default implementation errors; storage backends like S3ObjectBlockClient override this with actual download logic.

§Arguments
  • keys - Sequence hashes identifying each block
  • layout - Physical layout to write the block data into
  • block_ids - Block IDs within the layout to download into

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§