xchannel 1.3.0

mmap-backed IPC channels with regionized layout, alignment-safe headers, and file rolling.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use memmap2::{Mmap, MmapMut, MmapOptions};
use std::fs::File;
use std::{io, io::ErrorKind, slice};

pub type ReadOnly = Mmap;
pub type Writable = MmapMut;

/// Return the OS page size.
#[inline]
pub fn page_size() -> usize {
    // SAFETY: libc calls are safe here; fall back to 4096 if it fails.
    #[cfg(unix)]
    {
        let ps = unsafe { libc::sysconf(libc::_SC_PAGESIZE) };
        if ps > 0 { ps as usize } else { 4096 }
    }
}

/// Encapsulates a single mmap-ed region.
/// `Mode` is `Mmap` (read-only) or `MmapMut` (writable).
pub struct RegionMapping<Mode> {
    mmap: Mode,
    /// Region offset from the beginning of the file.
    region_offset: u64,
    /// Region size (multiple of OS page size).
    region_size: usize,
}

impl<Mode> RegionMapping<Mode> {
    #[inline]
    pub fn region_offset(&self) -> u64 {
        self.region_offset
    }
    #[inline]
    pub fn region_size(&self) -> usize {
        self.region_size
    }
}

fn check_alignment(base_offset: u64, region_size: usize) -> io::Result<()> {
    let ps = page_size();
    if region_size == 0 {
        return Err(io::Error::new(
            ErrorKind::InvalidInput,
            "region_size must be > 0",
        ));
    }
    if !region_size.is_multiple_of(ps) {
        return Err(io::Error::new(
            ErrorKind::InvalidInput,
            format!(
                "region_size ({}) must be a multiple of OS page size ({})",
                region_size, ps
            ),
        ));
    }
    if !base_offset.is_multiple_of(ps as u64) {
        return Err(io::Error::new(
            ErrorKind::InvalidInput,
            format!(
                "base_offset ({}) must be page-aligned (page={})",
                base_offset, ps
            ),
        ));
    }
    Ok(())
}

impl RegionMapping<Writable> {
    pub fn create_writable(file: &File, base_offset: u64, region_size: usize) -> io::Result<Self> {
        check_alignment(base_offset, region_size)?;
        let required_len = base_offset + region_size as u64;
        if file.metadata()?.len() < required_len {
            file.set_len(required_len)?;
        }

        let mmap = unsafe {
            let mut opts = MmapOptions::new();
            opts.offset(base_offset).len(region_size);
            // Prefer MAP_POPULATE on Linux to avoid first-touch stalls
            #[cfg(target_os = "linux")]
            let mmap = opts.populate().map_mut(file)?;
            #[cfg(not(target_os = "linux"))]
            let mmap = opts.map_mut(file)?;
            mmap
        };

        Ok(Self {
            mmap,
            region_offset: base_offset,
            region_size,
        })
    }

    pub fn get_bytes_mut(&mut self, offset: usize, len: usize) -> Option<&mut [u8]> {
        if offset.checked_add(len)? > self.region_size {
            return None;
        }
        let ptr = self.mmap.as_mut_ptr().wrapping_add(offset);
        Some(unsafe { slice::from_raw_parts_mut(ptr, len) })
    }

    #[inline]
    pub fn as_ptr(&self) -> *const u8 {
        self.mmap.as_ptr()
    }
    #[inline]
    pub fn as_mut_ptr(&mut self) -> *mut u8 {
        self.mmap.as_mut_ptr()
    }
}

impl RegionMapping<ReadOnly> {
    pub fn create_read_only(file: &File, base_offset: u64, region_size: usize) -> io::Result<Self> {
        check_alignment(base_offset, region_size)?;
        let mmap = unsafe {
            let mut opts = MmapOptions::new();
            opts.offset(base_offset).len(region_size);
            #[cfg(target_os = "linux")]
            let mmap = opts.populate().map(file)?;
            #[cfg(not(target_os = "linux"))]
            let mmap = opts.map(file)?;
            mmap
        };
        Ok(Self {
            mmap,
            region_offset: base_offset,
            region_size,
        })
    }
    #[inline]
    pub fn as_ptr(&self) -> *const u8 {
        self.mmap.as_ptr()
    }
}