Feature: Make Batch a customizable type in RaftTypeConfig

[drmingdrmer]

Summary

Allow users to provide custom Batch implementations for memory allocation optimization, while providing a default implementation in crate::impls::Batch.

Motivation

The current Batch<T> type is internal (pub(crate)) and not customizable. Users who need custom memory allocation strategies (e.g., arena allocators, pre-allocated pools) cannot provide their own batch container implementation.

Current State

• Batch<T> is defined in openraft/src/base/batch/mod.rs as pub(crate) enum Batch<T>
• Two variants: Single(T) (inline, no heap) and Vec(Vec<T>) (heap-allocated)
• Used for batching: Batch<C::D>, Batch<C::Entry>, Batch<Option<CoreResponder<C>>>

Proposed Design

1. Define RaftBatch Trait

Create a trait in openraft/src/base/batch/ that captures the required interface:

pub trait RaftBatch<T>:
    OptionalSend + Sized + Default + Clone + Debug + Eq + IntoIterator<Item = T> + 'static
where
    T: OptionalSend + 'static,
{
    type Iter<'a>: Iterator<Item = &'a T> + ExactSizeIterator where T: 'a, Self: 'a;
    type IterMut<'a>: Iterator<Item = &'a mut T> + ExactSizeIterator where T: 'a, Self: 'a;

    fn from_item(item: T) -> Self;
    fn from_vec(vec: Vec<T>) -> Self;
    fn from_exact_iter<I: ExactSizeIterator<Item = T>>(iter: I) -> Self;

    fn len(&self) -> usize;
    fn is_empty(&self) -> bool { self.len() == 0 }
    fn first(&self) -> Option<&T>;
    fn last(&self) -> Option<&T>;

    fn iter(&self) -> Self::Iter<'_>;
    fn iter_mut(&mut self) -> Self::IterMut<'_>;

    fn extend(&mut self, other: Self);

    // Auto-implemented display methods
    fn display(&self) -> DisplayBatch<'_, T, Self> where T: Display { ... }
    fn display_n(&self, max: usize) -> DisplayBatch<'_, T, Self> where T: Display { ... }
}

2. Add to RaftTypeConfig

pub trait RaftTypeConfig: ... {
    /// Batch container type for grouping multiple items efficiently.
    type Batch<T>: RaftBatch<T> where T: OptionalSend + 'static;
}

3. Default Implementation

• Keep Batch<T> in openraft/src/base/batch/mod.rs
• Make it pub (currently pub(crate))
• Implement RaftBatch<T> trait for it
• Re-export from crate::impls::Batch

4. Update declare_raft_types! Macro

Add default:

(Batch<T>, , $crate::impls::Batch<T> where T: $crate::OptionalSend + 'static),

Files to Modify

File	Change
openraft/src/base/batch/raft_batch.rs	New: Define RaftBatch trait
openraft/src/base/batch/mod.rs	Make Batch public, impl RaftBatch
openraft/src/base/mod.rs	Export RaftBatch trait
openraft/src/type_config.rs	Add Batch<T> associated type
openraft/src/impls/mod.rs	Re-export Batch from base
openraft/src/raft/mod.rs	Update declare_raft_types! macro
openraft/src/lib.rs	Export RaftBatch trait
openraft/src/core/raft_msg/mod.rs	Use C::Batch<_>
openraft/src/engine/command.rs	Use C::Batch<_>
openraft/src/raft/api/app.rs	Use C::Batch<_>
openraft/src/core/merged_raft_msg_receiver.rs	Use C::Batch<_>

[github-actions]

👋 Thanks for opening this issue!

Get help or engage by:

• /help : to print help messages.
• /assignme : to assign this issue to you.

[Lymah123]

Hi @drmingdrmer , can I hop on this issue?

[drmingdrmer]

Hi @drmingdrmer , can I hop on this issue?

sure. Thank you!

If you have any question, please discuss here.

[Lymah123]

Hi @drmingdrmer

Implementation Status Update

The Batch customization feature is 98% complete but has hit a Rust type system limitation that requires a design adjustment.

** What's Working**

• RaftBatch trait defined with all required methods
• Batch<T> made public and implements the trait
• Associated type Batch<T> added to RaftTypeConfig
• All files updated to use C::Batch<_>
• Trait properly exported from base and lib

** Current Issue**

37 compilation errors, all with the same root cause:

error[E0277]: the trait bound `<C::Batch<T> as IntoIterator>::IntoIter: OptionalSend` is not satisfied

Root Cause

The trait requires IntoIterator as a supertrait with Self::IntoIter: OptionalSend in the where clause. However, Rust's type system cannot propagate where-clause bounds through associated type projections.

When code uses C::Batch<T> (an associated type), the compiler treats it as opaque and cannot prove that <C::Batch<T> as IntoIterator>::IntoIter satisfies the Send bound, even though the trait definition requires it.

This is why the original design comment said: "Ownership-based iteration (IntoIterator) is intentionally avoided."

Recommended Solution

Remove IntoIterator from the RaftBatch trait, while keeping it on the concrete Batch<T> implementation:

pub trait RaftBatch<T>: OptionalSend + Sized + Default + Debug + PartialEq + 'static
where T: OptionalSend + 'static
{
    // Remove: IntoIterator supertrait
    
    type Iter<'a>: Iterator<Item = &'a T> + ExactSizeIterator where T: 'a, Self: 'a;
    type IterMut<'a>: Iterator<Item = &'a mut T> + ExactSizeIterator where T: 'a, Self: 'a;
    
    // For consuming the batch
    fn into_vec(self) -> Vec<T>;
    
    // Borrowing iteration (existing)
    fn iter(&self) -> Self::Iter<'_>;
    fn iter_mut(&mut self) -> Self::IterMut<'_>;
    
    // ... rest of methods
}

// Concrete type keeps IntoIterator for convenience
impl<T> IntoIterator for Batch<T> { ... }  // Already exists

Changes Required:

1. Remove IntoIterator from RaftBatch trait definition
2. Add into_vec() method to trait and implement for Batch<T>
3. Update storage call sites to convert: log_store.append(entries.into_vec(), callback)
4. Use .iter() instead of .into_iter() elsewhere

Would you like me to prepare a PR with these changes?

[schreter]

Add into_vec() method to trait and implement for Batch<T>

This somehow defeats the purpose of minimizing memory allocations and streamlining the processing. Please try not to introduce yet another memory allocation in the data path.

Can't you just add the OptionalSend bound at the right place? Where exactly do you see the issue?

Alternatively, instead of implementing IntoIterator trait, can't you directly add into_iter() on the Batch?

Just my 2c.

[Lymah123]

Add into_vec() method to trait and implement for Batch<T>

This somehow defeats the purpose of minimizing memory allocations and streamlining the processing. Please try not to introduce yet another memory allocation in the data path.

Can't you just add the OptionalSend bound at the right place? Where exactly do you see the issue?

Alternatively, instead of implementing IntoIterator trait, can't you directly add into_iter() on the Batch?

Just my 2c.

You're absolutely right - adding into_vec() would defeat the entire purpose of the optimization. Thank you for pushing back on that!

Regarding Option 1 (Adding bounds at the right place):

The bound is already in the trait definition:

pub trait RaftBatch<T>: IntoIterator<Item = T> + ...
where Self::IntoIter: OptionalSend  // ← Already here

The issue is that when code uses the associated type C::Batch<T>, the compiler treats it as opaque and can't "see through" to the where-clause bounds. This means each call site would need explicit bounds like:

where <C::Batch<T> as IntoIterator>::IntoIter: Send

This would need to be added to ~20+ function signatures, which is verbose and defeats the purpose of trait abstraction.

Regarding Option 2 (Direct into_iter() method):

This is a much better approach! Instead of inheriting IntoIterator as a supertrait, we can make IntoIter an explicit associated type:

pub trait RaftBatch<T>: OptionalSend + Sized + Default + Debug + PartialEq + 'static
where T: OptionalSend + 'static
{
    type Iter<'a>: Iterator<Item = &'a T> + ExactSizeIterator where T: 'a, Self: 'a;
    type IterMut<'a>: Iterator<Item = &'a mut T> + ExactSizeIterator where T: 'a, Self: 'a;
    
    // Explicit IntoIter associated type (not from supertrait)
    type IntoIter: Iterator<Item = T> + ExactSizeIterator + OptionalSend;
    
    fn into_iter(self) -> Self::IntoIter;  // Direct method
    
    // ... rest of methods
}

This should work because Self::IntoIter is now a direct associated type of RaftBatch, which the compiler can see and reason about, rather than a projection from a supertrait.

Would you like me to implement Option 2 and test if it resolves the compilation errors?

[schreter]

Would you like me to implement Option 2 and test if it resolves the compilation errors?

Well, it should be fairly easy to try out, so go for it :-).

In the worst case, there is some code location which requires "true" IntoIterator.