Table of Contents

Introduction

AFIO single page cheat sheet for the very impatient

Design Introduction and Rationale

Write ordering constraints, and how these can be used to achieve some of the Durability in ACID without needing fsync()

Background on how filing systems work

Write ordering data and durability: why does it matter?

Compilation

Quick Start Tutorial

Step by step workshop building an AFIO-based key-value store

1. World's simplest named blob store in STL iostreams

2. World's simplest named blob store in AFIO (synchronous)

3. World's simplest named blob store in AFIO (asynchronous)

The problems with this naive design

4. Second attempt at a key-value store: How to implement atomic value updates and therefore Atomicity, Consistency, Isolation and Durability

The performance of and problems with this second generation design

5. Third attempt at a key-value store: Thinking like a filing system

The final named blob store design

The performance of and problems with this third generation design

Example mini-programs written using AFIO

Hello World, asynchronously!

A less toy example: Concatenating files

Achieving atomicity on the filing system

Handling races on the filing system

What performance benefit does asynchronous file i/o bring me? A demonstration

Reference

Macros and Flags

BOOST_AFIO_VALIDATE_INPUTS

file_flags

fs_metadata_flags

metadata_flags

Structures

enumerate_req

filter

io_req

io_req

io_req< const T >

io_req< void >

io_req< const void >

path_req

path_req::absolute

path_req::relative

stat_t

statfs_t

statfs_t::f_flags_t

Classes

current_dispatcher_guard

directory_entry

directory_entry_hash

dispatcher

complete_async_op (normal)

complete_async_op (errored)

enqueued_task< R()>

future

future< void >

handle

open_states

handle::mapped_file

path

direntry

target

link

unlink

atomic_relink

path

path::make_absolute

normalise_path

path_hash

thread_source

std_thread_pool

Functions

current_dispatcher

make_dispatcher

depends

make_io_req (length deducing)

make_io_req (length deducing)

make_io_req (length specifying)

process_threadpool

Functions for opening/creating directories

dir (batch)

async_dir (relative)

async_dir (absolute)

dir (relative throwing)

dir (absolute throwing)

dir (relative non throwing)

dir (absolute non throwing)

Functions for deleting directories

rmdir (batch)

async_rmdir (relative)

async_rmdir (absolute)

rmdir (relative throwing)

rmdir (absolute throwing)

rmdir (relative non throwing)

rmdir (absolute non throwing)

Functions for opening/creating files

file (batch)

async_file (relative)

async_file (absolute)

file (relative throwing)

file (absolute throwing)

file (relative non throwing)

file (absolute non throwing)

Functions for deleting files

rmfile (batch)

async_rmfile (relative)

async_rmfile (absolute)

rmfile (relative throwing)

rmfile (absolute throwing)

rmfile (relative non throwing)

rmfile (absolute non throwing)

Functions for opening/creating symlinks

symlink (batch)

async_symlink (relative)

async_symlink (absolute)

symlink (relative throwing)

symlink (absolute throwing)

symlink (relative non throwing)

symlink (absolute non throwing)

Functions for deleting symlinks

rmsymlink (batch)

async_rmsymlink (relative)

async_rmsymlink (absolute)

rmsymlink (relative throwing)

rmsymlink (absolute throwing)

rmsymlink (relative non throwing)

rmsymlink (absolute non throwing)

Functions for synchronising changes to physical storage

sync (batch)

async_sync

sync (throwing)

sync (non throwing)

Functions for deallocating/zeroing physical storage

zero (batch)

async_zero

zero (throwing)

zero (non throwing)

Functions for closing open handles

close (batch)

async_close

close (throwing)

close (non throwing)

Functions for scatter reading file contents

read (batch)

async_read (length deducing)

async_read (length specifying)

read (length deducing throwing)

read (length specifying throwing)

read (length deducing non throwing)

read (length specifying non throwing)

Functions for gather writing file contents

write (batch)

async_write (length deducing)

async_write (length specifying)

write (length deducing throwing)

write (length specifying throwing)

write (length deducing non throwing)

write (length specifying non throwing)

Functions for setting maximum file extent

truncate (batch)

async_truncate

truncate (throwing)

truncate (non throwing)

Functions for enumerating directory contents and fetching file metadata

enumerate (batch)

async_enumerate (maxitems first)

enumerate (max items first throwing)

enumerate (max items first non throwing)

async_enumerate (glob first)

enumerate (glob first throwing)

enumerate (glob first non throwing)

async_enumerate (metadata first)

enumerate (metadata first throwing)

enumerate (metadata first non throwing)

Functions for enumerating file physical storage extents

extents (batch)

async_extents

extents (throwing)

extents (non throwing)

Functions for fetching storage volume metadata

statfs (batch)

async_statfs

statfs (throwing)

statfs (nonthrowing)

Specialisations for how types should be parsed into ASIO scatter/gather buffers

to_asio_buffers (asio mutable_buffer)

to_asio_buffers (asio const_buffer)

to_asio_buffers (buffer of T)

to_asio_buffers (const buffer of T)

to_asio_buffers (buffer)

to_asio_buffers (const buffer of T)

to_asio_buffers (trivial and container types)

to_asio_buffers (const trivial and container types)

to_asio_buffers (C arrays)

to_asio_buffers (const C arrays)

Utilities

Classes

utils::page_allocator

utils::secded_ecc

Functions in namespace utils

page_sizes

file_buffer_default_size

random_fill

to_hex_string

from_hex_string

random_string

Release Notes

Frequently Asked Questions

What is the maximum throughput of AFIO's closure execution engine aka how many IOPS can I push with AFIO?

What is the latency of AFIO's closure execution engine aka how quickly can I push a single op with AFIO?

I'm seeing “WARNING: ~async_file_dispatcher_base() detects stuck async_io_op in total of X ops” during process close. What does this mean?

Why did you use std::vector<> as the ops batch container instead of a generic iterator range?

How do I configure my own file descriptor or HANDLE in AFIO?

Using AFIO really slows down my compile times. Can't you do something about that?

Why do I get a fatal application exit with FATAL EXCEPTION: Failed to read all buffers when I read a file?

async_io_handle::direntry() and async_io_handle::lstat() are both synchronous functions which block. How then can I get metadata about files and directories asynchronously?

I thought on Windows it is impossible to delete a file which is still open for use. How does AFIO achieve this?

How do I reconfigure AFIO within the same translation unit to use a different ABI?

Acknowledgments

Index