Fields

• close :: HasCallStack => m ()

  (Idempotent) close the interface.

  Using submitIO after close should thrown an FsError exception. See mkClosedError.

• submitIO :: HasCallStack => Vector (IOOp (PrimState m) h) -> m (Vector IOResult)

  Submit a batch of I/O operations and wait for the result.

  Results correspond to input IOOps in a pair-wise manner, i.e., one can match IOOps with IOResults by indexing into both vectors at the same position.

  If any of the I/O operations fails, an FsError exception will be thrown.

• hSetNoCache :: Handle h -> Bool -> m ()

  Set the file data caching mode for a file handle.

  This has different effects on different distributions. * [Linux]: set the O_DIRECT flag. * [MacOS]: set the F_NOCACHE flag. * [Windows]: no-op.

  TODO: subsequent reads/writes with misaligned byte arrays should fail both in simulation and real implementation.

• hAdvise :: Handle h -> FileOffset -> FileOffset -> Advice -> m ()

  Predeclare an access pattern for file data.

  This has different effects on different distributions. * [Linux]: perform @posix_fadvise(2). * [MacOS]: no-op. * [Windows]: no-op.

• hAllocate :: Handle h -> FileOffset -> FileOffset -> m ()

  Allocate file space.

  This has different effects on different distributions. * [Linux]: perform @posix_fallocate(2). * [MacOS]: no-op. * [Windows]: no-op.

• tryLockFile :: FsPath -> LockMode -> m (Maybe (LockFileHandle m))

  Try to acquire a file lock without blocking.

  This uses different locking methods on different distributions. * [Linux]: Open file descriptor (OFD) * [MacOS]: flock * [Windows]: LockFileEx

  This function can throw FileLockingNotSupported when file locking is not supported.

  NOTE: though it would have been nicer to allow locking file handles instead of file paths, it would make the implementation of this function in IO much more complex. In particular, if we want to reuse GHC.IO.Handle.Lock functionality, then we have to either ...

  1. Convert there and back between OS-specific file desciptors and Handles, which is not possible on Windows without creating new file descriptors, or ...
  2. Vendor all of the GHC.IO.Handle.Lock code and its dependencies (i.e., modules), which is a prohibitively large body of code for GHC versions before 9.0.

  The current interface is therefore limited, but should be sufficient for use cases where a lock file is used to guard against concurrent access by different processes. e.g., a database lock file.

  TODO: it is probably possible to provide a onLockFileHandle function that allows you to use LockFileHandle as a Handle, but only within a limited scope. That is, it has to fit the style of withHandleToHANDLE :: Handle -> (HANDLE -> IO a) -> IO a from the Win32 package.

• hSynchronise :: Handle h -> m ()

  Synchronise file contents with the storage device.

  Ensure that all change to the file handle's contents which exist only in memory (as buffered system cache pages) are transfered/flushed to disk. This will also update the file handle's associated metadata.

  This uses different system calls on different distributions. * [Linux]: fsync(2) * [MacOS]: fsync(2) * [Windows]: flushFileBuffers

• synchroniseDirectory :: FsPath -> m ()

  Synchronise a directory with the storage device.

  This uses different system calls on different distributions. * [Linux]: fsync(2) * [MacOS]: fsync(2) * [Windows]: no-op

• createHardLink :: FsPath -> FsPath -> m ()

  Create a hard link for an existing file at the source path and a new file at the target path.

  This uses different system calls on different distributions. * [Linux]: link * [MacOS]: link * [Windows]: CreateHardLinkW

Fields

• ioctxBatchSizeLimit :: !Int
   
• ioctxConcurrencyLimit :: !Int
   

Fields

• hUnlock :: m ()

  Release a file lock acquired using tryLockFile.