p-x9/swift-fileio

Supported Platforms

| Platform | MemoryMappedFile | StreamedFile | Concatenated* | |---|---|---|---| | Apple platforms | ✅ | ✅ | ✅ | | Linux (glibc) | ✅ | ✅ | ✅ | | Linux (musl / Static Linux SDK) | ✅ | ✅ | ✅ | | Android | ✅ | ✅ | ✅ | | Windows | ✅ | ✅ | ✅ |

All of these are built and tested in CI, except Android and the Static Linux SDK, which are cross-compiled and so build-only.

Features

• MemoryMappedFile: using mmap
• StreamedFile: using FileHandle (syscall)

• ConcatenatedMemoryMappedFile: using mmap. Treats multiple files as one continuous virtual file. Each file is mapped independently and the concatenation is logical, so there is no whole-file pointer and no constraint on the individual file sizes. Zero-copy access goes through unsafeRegion(at:).
• StreamedFile: using FileHandle (syscall). Treats multiple files as one continuous virtual file.

Usage

MemoryMappedFile/StreamedFile have the same API available for both.

Available methods are defined in the FileIOProtocol

Design Overview

This library separates file I/O into three orthogonal concerns:

1. Capability: what operations are supported (_FileIOProtocol)
2. Role: how the object is used (FileIOProtocol, FileIOSiliceProtocol)
3. Implementation strategy: how I/O is performed (memory-mapped or streamed)

Protocol Relationships

The following diagram illustrates the relationships between the core protocols in this library.

graph TD
    _FileIOProtocol --> FileIOProtocol
    _FileIOProtocol --> FileIOSiliceProtocol

    _FileIOProtocol --> _MemoryMappedFileIOProtocol
    _FileIOProtocol --> _StreamedFileIOProtocol

    FileIOProtocol --> MemoryMappedFileIOProtocol
    FileIOProtocol --> StreamedFileIOProtocol

    _MemoryMappedFileIOProtocol --> _SingleMemoryMappedFileIOProtocol
    _MemoryMappedFileIOProtocol --> MemoryMappedFileIOProtocol
    _StreamedFileIOProtocol --> StreamedFileIOProtocol

    FileIOProtocol --> FileSlice[associatedtype FileSlice]
    FileSlice --> FileIOSiliceProtocol

    _FileIOProtocol --> ResizableFileIOProtocol

• _FileIOProtocol defines the fundamental read/write and synchronization operations.
• FileIOProtocol extends it with file-opening and slicing capabilities.
• FileIOSiliceProtocol represents a logical view into a file with a baseOffset.
• ResizableFileIOProtocol adds structural mutation operations such as insert and delete. Only whole-file types adopt it; slices do not.
• Changing a file's length invalidates every slice taken from it beforehand — all of them, not only the ones whose bytes moved, since nothing records which ranges a mutation shifted. isValid reports this, and the remedy is to take the slice again.
• A stale slice throws FileIOError.staleSlice from everything that can throw. sync() and refresh() have no failure channel and do nothing at all, and MemoryMappedFileSlice.ptr is unchecked and can still hand back a pointer outside the mapping — use unsafeRegion(at:) for the checked form.
• _MemoryMappedFileIOProtocol and _StreamedFileIOProtocol describe low-level implementation traits.
• _MemoryMappedFileIOProtocol requires unsafeRegion(at:), which returns a pointer and how far the memory stays contiguous from it. Both mapping strategies can satisfy this, so generic code written against it works with either.
• _SingleMemoryMappedFileIOProtocol adds ptr, a base pointer for the whole file. MemoryMappedFile has one; ConcatenatedMemoryMappedFile maps each of its files separately and genuinely does not, so it adopts only the former.
• MemoryMappedFileIOProtocol and StreamedFileIOProtocol combine implementation traits with FileIOProtocol.

License

FileIO is released under the MIT License. See LICENSE

Package Metadata

Repository: p-x9/swift-fileio

Default branch: main

README: README.md