Safe Haskell	Safe-Inferred
Language	GHC2021

System.FS.BlockIO.IO

Contents

Implementation details
Initialisation
- Parameters
- Unsafe

Description

Implementations using the real file system.

The implementation of the HasBlockIO interface provided in this module is platform-dependent. Most importantly, on Linux, the implementation of submitIO is backed by blockio-uring: a library for asynchronous I/O. On Windows and MacOS, the implementation of submitIO only supports serial I/O.

Synopsis

ioHasBlockIO :: MountPoint -> IOCtxParams -> IO (HasFS IO HandleIO, HasBlockIO IO HandleIO)
withIOHasBlockIO :: MountPoint -> IOCtxParams -> (HasFS IO HandleIO -> HasBlockIO IO HandleIO -> IO a) -> IO a
data IOCtxParams = IOCtxParams {
- ioctxBatchSizeLimit :: !Int
- ioctxConcurrencyLimit :: !Int
}
defaultIOCtxParams :: IOCtxParams
unsafeFromHasFS :: HasFS IO HandleIO -> IOCtxParams -> IO (HasBlockIO IO HandleIO)
withUnsafeFromHasFS :: HasFS IO HandleIO -> IOCtxParams -> (HasBlockIO IO HandleIO -> IO a) -> IO a

Implementation details

Though the HasBlockIO interface tries to capture uniform behaviour, each function in this implementation for the real file system can have subtly different effects depending on the underlying patform. For example, some features are not provided by some operating systems, and in some cases the features behave subtly differently for different operating systems. For this reason, we include below some documentation about the effects of calling the interface functions on different platforms.

Note: if the serialblockio Cabal flag is enabled, then the Linux implementation uses a mocked context and serial I/O for close and submitIO, just like the MacOS and Windows implementations do.

IO context: When an instance of the HasBlockIO interface for Linux systems is initialised, an io_uring context is created using the blockio-uring package and stored in the HasBlockIO closure. For uniform behaviour, each other platform creates and stores a mocked IO context that has the same open/closed behaviour as an io_uring context. In summary, each platform creates:

Linux: an io_uring context provided by the blockio-uring package
MacOS: a mocked context using an MVar
Windows: a mocked conext using an MVar

close

Linux: close the io_uring context through the blockio-uring package
MacOS: close the mocked context
Windows: close the mocked context

submitIO: Submit a batch of I/O operations using:

Linux: the submitIO function from the blockio-uring package
MacOS: serial I/O using a HasFS
Windows: serial I/O using a HasFS

hSetNoCache

Linux: set the O_DIRECT flag
MacOS: set the F_NOCACHE flag
Windows: no-op

hAdvise

Linux: perform posix_fadvise(2)
MacOS: no-op
Windows: no-op

hAllocate

Linux: perform posix_fallocate(2)
MacOS: no-op
Windows: no-op

tryLockFile: This uses different locking methods depending on the OS.

Linux: Open file descriptor (OFD)
MacOS: flock
Windows: LockFileEx

hSynchronise

Linux: perform fsync(2)
MacOS: perform fsync(2)
Windows: perform flushFileBuffers

synchroniseDirectory

Linux: perform fsync(2)
MacOS: perform fsync(2)
Windows: no-op

createHardLink

Linux: perform link
MacOS: perform link
Windows: perform CreateHardLinkW

Initialisation

ioHasBlockIO :: MountPoint -> IOCtxParams -> IO (HasFS IO HandleIO, HasBlockIO IO HandleIO) Source #

An implementation of the HasBlockIO interface using the real file system.

Make sure to use close the resulting HasBlockIO when it is no longer used. withIOHasBlockIO does this automatically.

The HasFS interface is instantiated using ioHasFS.

withIOHasBlockIO :: MountPoint -> IOCtxParams -> (HasFS IO HandleIO -> HasBlockIO IO HandleIO -> IO a) -> IO a Source #

Perform an action using a HasFS and a HasBlockIO instance. The latter is only open for the duration of the action.

The HasFS and HasBlockIO interfaces are initialised using ioHasBlockIO.

Parameters

data IOCtxParams Source #

Concurrency parameters for initialising the IO context in a HasBlockIO instance.

IO context parameters: These parameters are interpreted differently based on the underlying platform:

Linux: Pass the parameters to initIOCtx in the blockio-uring package
MacOS: Ignore the parameters
Windows: Ignore the parameters

For more information about what these parameters mean and how to configure them, see the blockio-uring package.

Constructors

IOCtxParams
Fields ioctxBatchSizeLimit :: !Int ioctxConcurrencyLimit :: !Int

Instances

Instances details

NFData IOCtxParams Source #
Instance details Defined in System.FS.BlockIO.IO.Internal Methods rnf :: IOCtxParams -> () #

defaultIOCtxParams :: IOCtxParams Source #

Default parameters. Some manual tuning of parameters might be required to achieve higher performance targets (see IOCtxParams).

Unsafe

unsafeFromHasFS :: HasFS IO HandleIO -> IOCtxParams -> IO (HasBlockIO IO HandleIO) Source #

An implementation of the HasBlockIO interface using the real file system.

Make sure to use close the resulting HasBlockIO when it is no longer used. withUnsafeFromHasFS does this automatically.

Unsafe

You will probably want to use ioHasBlockIO or withIOHasBlockIO instead.

Only a HasFS for the real file system, like ioHasFS, should be passed to unsafeFromHasFS. Technically, one could pass a HasFS for a simulated file system, but then the resulting HasBlockIO would contain a mix of simulated and real functions, which is probably not what you want.

withUnsafeFromHasFS :: HasFS IO HandleIO -> IOCtxParams -> (HasBlockIO IO HandleIO -> IO a) -> IO a Source #

Perform an action using a HasBlockIO instance that is only open for the duration of the action.

The HasBlockIO is initialised using unsafeFromHasFS.

Unsafe

You will probably want to use ioHasBlockIO or withIOHasBlockIO instead.

Only a HasFS for the real file system, like ioHasFS, should be passed to withUnsafeFromHasFS. Technically, one could pass a HasFS for a simulated file system, but then the resulting HasBlockIO would contain a mix of simulated and real functions, which is probably not what you want.