blockio: document the API module

We remove documentation about implementation specifics from the `HasBlockIO`
type, but we'll include it in the `IO` module in one of the next commits.

Author: jorisdral

blockio/src/System/FS/BlockIO/API.hs

@@ -1,6 +1,7 @@
 {-# LANGUAGE TypeFamilies  #-}
 {-# LANGUAGE UnboxedTuples #-}
 
+-- | Abstract interface, types, and utilities.
 module System.FS.BlockIO.API (
     -- * HasBlockIO
     HasBlockIO (..)
@@ -45,55 +46,80 @@ import           System.FS.API (BufferOffset, FsPath, Handle (..), HasFS)
 import           System.Posix.Types (ByteCount, FileOffset)
 import           Text.Printf
 
--- | Abstract interface for submitting large batches of I\/O operations.
+-- | Abstract interface for submitting large batches of I\/O operations. This
+-- interface is an extension of the 'HasFS' interface that is provided by the
+-- @fs-api@ package.
+--
+-- The interface tries to specify uniform behaviour, but each implementation can
+-- have subtly different effects for a variety of reasons. However, for the most
+-- part the underlying implementation of an instance of the interface should not
+-- affect the correctness of programs that use the interface.
+--
+-- For uniform behaviour across implementations, functions that create a new
+-- instance of the interface should initialise an IO context. This IO context
+-- may be of any shape, as long as the context has two modes: open and closed.
+-- This context is only important for the 'close' and 'submitIO' functions. As
+-- long as the IO context is open, 'submitIO' should perform batches of I\/O
+-- operations as expected, but 'submitIO' should throw an error as soon as the
+-- IO context is closed. Once the IO context is closed, it can not be re-opened
+-- again. Instead, the user should create a new instance of the interface.
+--
+-- Note: there are a bunch of functions in the interface that have nothing to do
+-- with submitting large batches of I/O operations. In fact, only 'close' and
+-- 'submitIO' are related to that. All other functions were put in this record
+-- for simplicity because the authors of the library needed them and it was more
+-- straightforward to add them here then to add them to @fs-api@. Still these
+-- unrelated functions could and should all be moved into @fs-api@ at some point
+-- in the future.
+--
+-- === Implementations
+--
+-- There are currently two known implementations of the interface:
+--
+-- * An implementation using the real file system, which can be found in the
+--   "System.FS.BlockIO.IO" module. This implementation is platform-dependent.
+--
+-- * An implementation using a simulated file system, which can be found in the
+--   @System.FS.BlockIO.Sim@ module of the @blockio:sim@ sublibrary. This
+--   implementation is uniform across platforms.
+--
 data HasBlockIO m h = HasBlockIO {
-    -- | (Idempotent) close the interface.
+    -- | (Idempotent) close the IO context that is required for running
+    -- 'submitIO'.
+    --
+    -- Using 'submitIO' after 'close' throws an 'FsError' exception.
     --
-    -- Using 'submitIO' after 'close' should thrown an 'FsError' exception. See
-    -- 'mkClosedError'.
     close    :: HasCallStack => m ()
+
     -- | Submit a batch of I\/O operations and wait for the result.
     --
     -- Results correspond to input 'IOOp's in a pair-wise manner, i.e., one can
     -- match 'IOOp's with 'IOResult's by indexing into both vectors at the same
     -- position.
     --
     -- If any of the I\/O operations fails, an 'FsError' exception will be thrown.
+    --
   , submitIO :: HasCallStack => V.Vector (IOOp (PrimState m) h) -> m (VU.Vector IOResult)
+
+    -- TODO: once file caching is disabled, subsequent reads/writes with
+    -- misaligned byte arrays should throw an error. Preferably, this should
+    -- happen in both the simulation and real implementation, even if the real
+    -- implementation does not support setting the file caching mode. This would
+    -- make the behaviour of the file caching mode more uniform across
+    -- implementations and platforms.
+
     -- | 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.
   , hSetNoCache :: Handle h -> Bool -> 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.
   , hAdvise :: Handle h -> FileOffset -> FileOffset -> Advice -> m ()
+
     -- | Allocate file space.
     --
-    -- This has different effects on different distributions.
-    -- * [Linux]: perform @posix_fallocate(2).
-    -- * [MacOS]: no-op.
-    -- * [Windows]: no-op.
   , hAllocate :: Handle h -> FileOffset -> FileOffset -> 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 'GHC.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
@@ -114,35 +140,34 @@ data HasBlockIO m h = HasBlockIO {
     -- 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.
+
+    -- | Try to acquire a file lock without blocking.
+    --
+    -- This function throws 'GHC.FileLockingNotSupported' when file locking is
+    -- not supported.
+    --
   , tryLockFile :: FsPath -> GHC.LockMode -> m (Maybe (LockFileHandle 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 transferred/flushed to disk.
-    -- This will also update the file handle's associated metadata.
+    -- This ensures that all changes to the file handle's contents, which might
+    -- exist only in memory as buffered system cache pages, are
+    -- transferred/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@
   , hSynchronise :: Handle h -> 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
+    -- This ensures that all changes to the directory, which might exist only in
+    -- memory as buffered changes, are transferred/flushed to disk. This will
+    -- also update the directory's associated metadata.
+    --
   , synchroniseDirectory :: 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@
   , createHardLink :: FsPath -> FsPath -> m ()
   }
 
@@ -195,7 +220,7 @@ instance VUM.Unbox IOResult
   Advice
 -------------------------------------------------------------------------------}
 
--- | Basically "System.Posix.Fcntl.Advice" from the @unix@ package
+-- | Copy of "System.Posix.Fcntl.Advice" from the @unix@ package
 data Advice =
     AdviceNormal
   | AdviceRandom
@@ -219,7 +244,7 @@ hDropCacheAll hbio h = hAdviseAll hbio h AdviceDontNeed
 -------------------------------------------------------------------------------}
 
 {-# SPECIALISE synchroniseFile :: HasFS IO h -> HasBlockIO IO h -> FsPath -> IO () #-}
--- | Synchronise a file and its contents with the storage device.
+-- | Synchronise a file's contents and metadata with the storage device.
 synchroniseFile :: MonadThrow m => HasFS m h -> HasBlockIO m h -> FsPath -> m ()
 synchroniseFile hfs hbio path =
     FS.withFile hfs path (FS.ReadWriteMode FS.MustExist) $ hSynchronise hbio
@@ -230,8 +255,8 @@ synchroniseFile hfs hbio path =
   -> FsPath
   -> IO ()
   #-}
--- | Synchronise a directory and recursively its contents with the storage
--- device.
+-- | Synchronise a directory's contents and metadata with the storage device,
+-- and recursively for all entries in the directory.
 synchroniseDirectoryRecursive ::
      MonadThrow m
   => HasFS m h