cache2 0.6.1

Performance-first bounded RAM and NVMe hybrid cache
Documentation
// Copyright 2026 ScopeDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! One owned-buffer Region span submission for the data path.
//!
//! A successful write completion advances only the written prefix. The
//! disposable-cache protocol establishes durability once, when publishing a
//! CLEAN image, and deliberately has no per-span sync.

use std::io;
use std::time::Duration;

use crate::io::background::BackgroundIoAttempt;
use crate::io::engine::BoundedIoRequest;
use crate::io::engine::CACHE_IO_COMPLETION_TIMEOUT;
use crate::io::engine::IoBuffer;
use crate::io::engine::IoEngine;
use crate::io::engine::IoOperation;
use crate::io::engine::submit_background_io;
use crate::io::file::DIRECT_IO_ALIGNMENT;
use crate::io::file::WritePoint;
use crate::region::manager::RegionWriteSpan;
use crate::region::recovery::DataGeometry;

#[derive(Debug)]
pub struct WriteSubmitError {
    pub error: io::Error,
    pub buffer: IoBuffer,
}

pub struct PendingWrite {
    span: RegionWriteSpan,
    expected_len: usize,
    request: BoundedIoRequest,
}

pub struct WriteCompletion {
    pub span: RegionWriteSpan,
    pub result: io::Result<()>,
    pub buffer: Option<IoBuffer>,
}

impl PendingWrite {
    pub fn wait(self, engine: &IoEngine, attempt: &mut BackgroundIoAttempt<'_>) -> WriteCompletion {
        let completion = match self.request.wait_background(engine, attempt) {
            Ok(completion) => completion,
            Err(timeout) => {
                let (error, buffer) = timeout.into_buffer();
                return WriteCompletion {
                    span: self.span,
                    result: Err(error),
                    buffer,
                };
            }
        };
        let (io_result, buffer) = completion.into_io_result();
        let result = io_result.and_then(|completed| {
            if completed != self.expected_len {
                return Err(io::Error::new(
                    io::ErrorKind::UnexpectedEof,
                    "Region span write completed with the wrong byte count",
                ));
            }
            let Some(buffer) = buffer.as_ref() else {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "Region span completion did not return its owned buffer",
                ));
            };
            if buffer.len() != self.expected_len {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "Region span completion returned a buffer with the wrong length",
                ));
            }
            Ok(())
        });
        WriteCompletion {
            span: self.span,
            result,
            buffer,
        }
    }
}

// The error returns the owned aligned buffer without another fallible
// allocation; boxing it would violate that overload-path property.
pub fn submit_write(
    engine: &IoEngine,
    geometry: DataGeometry,
    span: RegionWriteSpan,
    buffer: IoBuffer,
    attempt: &mut BackgroundIoAttempt<'_>,
) -> Result<PendingWrite, WriteSubmitError> {
    submit_write_with_timeout(
        engine,
        geometry,
        span,
        buffer,
        CACHE_IO_COMPLETION_TIMEOUT,
        attempt,
    )
}

fn submit_write_with_timeout(
    engine: &IoEngine,
    geometry: DataGeometry,
    span: RegionWriteSpan,
    buffer: IoBuffer,
    timeout: Duration,
    attempt: &mut BackgroundIoAttempt<'_>,
) -> Result<PendingWrite, WriteSubmitError> {
    let (expected_len, absolute) = match validate_span(geometry, span) {
        Ok(validated) => validated,
        Err(error) => {
            return Err(WriteSubmitError { error, buffer });
        }
    };
    if buffer.len() != expected_len {
        return Err(WriteSubmitError {
            error: io::Error::new(
                io::ErrorKind::InvalidInput,
                "staging job does not match its Region span",
            ),
            buffer,
        });
    }
    let buffer_is_direct_aligned = buffer.as_slice().is_ok_and(|bytes| {
        (bytes.as_ptr() as usize).is_multiple_of(DIRECT_IO_ALIGNMENT)
            && bytes.len() % DIRECT_IO_ALIGNMENT == 0
    });
    if !buffer_is_direct_aligned {
        return Err(WriteSubmitError {
            error: io::Error::new(
                io::ErrorKind::InvalidInput,
                "Region span buffer is not direct-I/O aligned",
            ),
            buffer,
        });
    }
    let request = match submit_background_io(
        engine,
        IoOperation::write(WritePoint::Record, buffer, absolute),
        timeout,
        attempt,
    ) {
        Ok(request) => request,
        Err(error) => {
            let (error, buffer) = error.into_buffer();
            return Err(WriteSubmitError { error, buffer });
        }
    };
    Ok(PendingWrite {
        span,
        expected_len,
        request,
    })
}

fn validate_span(geometry: DataGeometry, span: RegionWriteSpan) -> io::Result<(usize, u64)> {
    if !geometry.is_valid()
        || !span.start_offset.is_multiple_of(DIRECT_IO_ALIGNMENT as u64)
        || !span.end_offset.is_multiple_of(DIRECT_IO_ALIGNMENT as u64)
        || span.end_offset <= span.start_offset
        || span.record_count == 0
    {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            "invalid Region write span",
        ));
    }
    let length_u64 = span.end_offset - span.start_offset;
    let length = usize::try_from(length_u64).map_err(|_| {
        io::Error::new(
            io::ErrorKind::InvalidInput,
            "Region write span length is invalid",
        )
    })?;
    let absolute = geometry
        .span_offset(span.region_id, span.start_offset, length_u64)
        .ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "Region write span exceeds the data file",
            )
        })?;
    Ok((length, absolute))
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;
    use std::sync::Mutex;
    use std::thread;

    use super::*;
    use crate::io::background::IoRecovery;
    use crate::io::engine::IoEngine;
    use crate::io::file::PositionedIo;
    use crate::managed_memory::BufferLease;
    use crate::region::recovery::DATA_REGION_AREA_OFFSET;

    #[derive(Default)]
    struct RecordingIo {
        writes: Mutex<Vec<(WritePoint, u64, Vec<u8>)>>,
        delay: Duration,
    }

    impl PositionedIo for RecordingIo {
        fn read_at(&self, _buffer: &mut [u8], _offset: u64) -> io::Result<usize> {
            Err(io::Error::new(io::ErrorKind::Unsupported, "read unused"))
        }

        fn write_at(&self, point: WritePoint, buffer: &[u8], offset: u64) -> io::Result<usize> {
            thread::sleep(self.delay);
            self.writes
                .lock()
                .unwrap_or_else(|poisoned| poisoned.into_inner())
                .push((point, offset, buffer.to_vec()));
            Ok(buffer.len())
        }
    }

    fn geometry() -> DataGeometry {
        let region_size = 64 * 1024;
        let region_count = 2;
        DataGeometry {
            data_file_len: DataGeometry::expected_file_len(region_size, region_count).unwrap(),
            region_size,
            region_count,
        }
    }

    fn span() -> RegionWriteSpan {
        RegionWriteSpan {
            shard_id: 0,
            region_id: 1,
            start_offset: 0,
            end_offset: 4096,
            record_count: 3,
            max_seqno: 21,
        }
    }

    #[test]
    fn late_span_completion_remains_valid_and_keeps_engine_usable() {
        let io = Arc::new(RecordingIo {
            delay: Duration::from_millis(50),
            ..RecordingIo::default()
        });
        let engine = IoEngine::for_test(io.clone(), 1).unwrap();
        let mut lease = BufferLease::try_fixed(4096).unwrap();
        lease.prepared_mut(4096).unwrap().fill(0x5a);
        let io_recovery = IoRecovery::new(Some(Duration::from_secs(5)));
        let mut attempt = BackgroundIoAttempt::new(&io_recovery, None);
        let completion = submit_write_with_timeout(
            &engine,
            geometry(),
            span(),
            IoBuffer::for_write(lease, 4096).unwrap(),
            Duration::from_millis(20),
            &mut attempt,
        )
        .unwrap()
        .wait(&engine, &mut attempt);
        assert!(completion.result.is_ok());
        attempt.finish();
        assert!(!io_recovery.is_recovering());
        assert_eq!(completion.span, span());
        assert_eq!(
            completion.buffer.unwrap().as_slice().unwrap(),
            &[0x5a; 4096]
        );
        assert_eq!(io.writes.lock().unwrap().len(), 1);
        assert!(engine.try_reserve_read().is_ok());
        engine.shutdown().unwrap();
    }

    #[test]
    fn span_write_preserves_owned_buffer_and_maps_region_offset_exactly() {
        let io = Arc::new(RecordingIo::default());
        let engine = IoEngine::for_test(io.clone(), 1).unwrap();
        let mut lease = BufferLease::try_fixed(4096).unwrap();
        lease.prepared_mut(4096).unwrap().fill(0x5a);

        let buffer = IoBuffer::for_write(lease, 4096).unwrap();
        let io_recovery = IoRecovery::new(Some(Duration::ZERO));
        let mut attempt = BackgroundIoAttempt::new(&io_recovery, None);
        let completion = submit_write(&engine, geometry(), span(), buffer, &mut attempt)
            .unwrap()
            .wait(&engine, &mut attempt);
        assert!(completion.result.is_ok());
        assert_eq!(completion.span, span());
        assert!(completion.buffer.is_some());
        drop(completion.buffer);

        let writes = io
            .writes
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        assert_eq!(writes.len(), 1);
        assert_eq!(writes[0].0, WritePoint::Record);
        assert_eq!(
            writes[0].1,
            DATA_REGION_AREA_OFFSET + geometry().region_size
        );
        assert_eq!(writes[0].2, vec![0x5a; 4096]);
        drop(writes);
        engine.shutdown().unwrap();
    }

    #[test]
    fn invalid_span_returns_the_only_buffer_without_submitting_io() {
        let io = Arc::new(RecordingIo::default());
        let engine = IoEngine::for_test(io.clone(), 1).unwrap();
        let mut invalid = span();
        invalid.end_offset += 1;
        let buffer = IoBuffer::for_write(BufferLease::try_fixed(4096).unwrap(), 4096).unwrap();
        let original_buffer = buffer.as_slice().unwrap().as_ptr();
        let error = match submit_write(
            &engine,
            geometry(),
            invalid,
            buffer,
            &mut BackgroundIoAttempt::new(&IoRecovery::new(Some(Duration::ZERO)), None),
        ) {
            Err(error) => error,
            Ok(_) => panic!("unaligned span must not be submitted"),
        };
        assert_eq!(error.error.kind(), io::ErrorKind::InvalidInput);
        assert_eq!(error.buffer.as_slice().unwrap().as_ptr(), original_buffer);
        drop(error.buffer);
        assert!(
            io.writes
                .lock()
                .unwrap_or_else(|poisoned| poisoned.into_inner())
                .is_empty()
        );
        engine.shutdown().unwrap();
    }
}