Struct BatchWriterConfig 

pub struct BatchWriterConfig {
    pub prefetch_parallelism: usize,
    pub enable_prefetch: bool,
    pub use_optimized_merge: bool,
    pub use_bottom_up_rebuild: bool,
    pub enable_deferred_rebalancing: bool,
    pub force_deferred: bool,
    pub cache_written_nodes: bool,
}

Configuration for batch write operations.

BatchWriterConfig provides tunable settings for batch operations, allowing you to optimize performance for your specific storage backend and workload.

Fields

• prefetch_parallelism: Maximum ordered route-hydration batch width (default: 16)
• enable_prefetch: Legacy compatibility flag (default: true)
• use_optimized_merge: Whether to use two-pointer merge vs binary search (default: true)
• use_bottom_up_rebuild: Whether to use bottom-up rebuild strategy (default: false)
• enable_deferred_rebalancing: Whether to enable deferred rebalancing optimization (default: true)
• force_deferred: Force deferred rebalancing regardless of pattern detection (default: false)
• cache_written_nodes: Warm the in-process node cache after successful batch writes (default: false)

Example

use prolly::BatchWriterConfig;

// Create with defaults
let config = BatchWriterConfig::default();

// Create with builder pattern
let config = BatchWriterConfig::new()
    .with_prefetch_parallelism(32)
    .with_prefetch(true)
    .with_optimized_merge(true)
    .with_bottom_up_rebuild(true)
    .with_deferred_rebalancing(true)
    .with_force_deferred(false)
    .with_cache_written_nodes(false);

Fields

prefetch_parallelism: usize

Maximum ordered route-hydration batch width.

Controls how many node CIDs are fetched per ordered batch while routing random updates through stores that prefer batched reads. Higher values may improve high-latency stores but increase transient memory usage.

enable_prefetch: bool

Legacy compatibility flag for speculative leaf prefetch.

Current route planning hydrates the affected leaves before mutation application, so the writer does not issue a second post-routing prefetch. Stores that prefer batched reads still use ordered batched route planning even when this is disabled, because that path is required node hydration rather than speculative prefetch.

use_optimized_merge: bool

Whether to use the optimized two-pointer merge algorithm.

When enabled, uses O(n+m) two-pointer merge instead of O(m log n) binary search approach. Should generally be left enabled unless debugging or comparing performance.

use_bottom_up_rebuild: bool

Whether to use bottom-up rebuild strategy for parent reconstruction.

When enabled, uses a bottom-up approach to rebuild parent nodes after leaf modifications. This can be more efficient when multiple leaves are modified, as it ensures each node is written exactly once.

The bottom-up rebuild strategy:

1. Applies mutations to all affected leaves
2. Rebuilds parent nodes from leaves to root in a single pass
3. Ensures each modified node is written exactly once

This is particularly beneficial for large batch operations that affect many leaves across the tree.

enable_deferred_rebalancing: bool

Whether to enable deferred rebalancing optimization.

When enabled, the batch processor will:

1. Detect append patterns and single-leaf groups
2. Apply all mutations before rebalancing
3. Rebuild the tree in a single bottom-up pass

Default: true (enabled)

force_deferred: bool

Force deferred rebalancing regardless of pattern detection.

When true, deferred rebalancing is used even if the pattern detection would normally disable it. Useful for testing or when the caller knows the access pattern.

Default: false

cache_written_nodes: bool

Whether to cache newly written nodes after a successful batch flush.

When enabled, read-after-write workloads such as immediate random get, diff, stream_diff, range_diff, or merge validation can reuse the rewritten frontier without fetching it back from the store. Keep this disabled for pure write-heavy ingest jobs where cache memory and cache-warming CPU are not worth paying during the write.

Default: false

Implementations

impl BatchWriterConfig

pub fn new() -> Self

Create a new configuration with default values.

Returns

A new BatchWriterConfig with:

• prefetch_parallelism: 16
• enable_prefetch: true
• use_optimized_merge: true
• use_bottom_up_rebuild: false
• enable_deferred_rebalancing: true
• force_deferred: false
• cache_written_nodes: false

Example

use prolly::BatchWriterConfig;

let config = BatchWriterConfig::new();
assert_eq!(config.prefetch_parallelism, 16);
assert!(config.enable_prefetch);
assert!(config.use_optimized_merge);
assert!(!config.use_bottom_up_rebuild);
assert!(config.enable_deferred_rebalancing);
assert!(!config.force_deferred);
assert!(!config.cache_written_nodes);

pub fn with_prefetch_parallelism(self, parallelism: usize) -> Self

Set the prefetch parallelism level.

Arguments

• parallelism - Maximum concurrent prefetch operations

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

let config = BatchWriterConfig::new()
    .with_prefetch_parallelism(32);
assert_eq!(config.prefetch_parallelism, 32);

pub fn with_prefetch(self, enabled: bool) -> Self

Set the legacy prefetch compatibility flag.

The current writer hydrates affected leaves during route planning and does not issue a second post-routing leaf prefetch. This setter is kept for source compatibility and for callers that inspect the config.

Arguments

• enabled - Stored value for the legacy prefetch flag

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

let config = BatchWriterConfig::new()
    .with_prefetch(false);
assert!(!config.enable_prefetch);

pub fn with_optimized_merge(self, enabled: bool) -> Self

Enable or disable the optimized two-pointer merge algorithm.

Arguments

• enabled - Whether to use optimized merge

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

// Use binary search approach (for comparison/debugging)
let config = BatchWriterConfig::new()
    .with_optimized_merge(false);
assert!(!config.use_optimized_merge);

pub fn with_bottom_up_rebuild(self, enabled: bool) -> Self

Enable or disable the bottom-up rebuild strategy.

When enabled, uses a bottom-up approach to rebuild parent nodes after leaf modifications. This can be more efficient when multiple leaves are modified, as it ensures each node is written exactly once.

Arguments

• enabled - Whether to use bottom-up rebuild

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

// Enable bottom-up rebuild for large batch operations
let config = BatchWriterConfig::new()
    .with_bottom_up_rebuild(true);
assert!(config.use_bottom_up_rebuild);

pub fn with_deferred_rebalancing(self, enabled: bool) -> Self

Enable or disable deferred rebalancing optimization.

When enabled, the batch processor will:

1. Detect append patterns and single-leaf groups
2. Apply all mutations before rebalancing
3. Rebuild the tree in a single bottom-up pass

This optimization significantly improves performance for append patterns (inserting keys at the end of the tree) by avoiding cascading splits.

Arguments

• enabled - Whether to enable deferred rebalancing

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

// Disable deferred rebalancing to use standard sequential approach
let config = BatchWriterConfig::new()
    .with_deferred_rebalancing(false);
assert!(!config.enable_deferred_rebalancing);

pub fn with_force_deferred(self, force: bool) -> Self

Force deferred rebalancing regardless of pattern detection.

When enabled, deferred rebalancing is used even if the pattern detection would normally disable it. This is useful for testing or when the caller knows the access pattern in advance.

Note: This setting only has effect when enable_deferred_rebalancing is also true.

Arguments

• force - Whether to force deferred rebalancing

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

// Force deferred rebalancing for testing
let config = BatchWriterConfig::new()
    .with_force_deferred(true);
assert!(config.force_deferred);

pub fn with_cache_written_nodes(self, enabled: bool) -> Self

Enable or disable cache warming for nodes written by batch operations.

This is useful when a workload performs random updates and then immediately reads, diffs, streams diffs, range-diffs, or merges the updated tree. It should usually stay disabled for write-only ingest.

Arguments

• enabled - Whether to cache newly written batch nodes after flush

Returns

Self for method chaining

Example

use prolly::BatchWriterConfig;

let config = BatchWriterConfig::new()
    .with_cache_written_nodes(true);
assert!(config.cache_written_nodes);

Trait Implementations

impl Clone for BatchWriterConfig

fn clone(&self) -> BatchWriterConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BatchWriterConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BatchWriterConfig

fn default() -> Self

Returns the “default value” for a type.