Safe Haskell	Safe-Inferred
Language	GHC2021

System.FS.BlockIO.API

Contents

HasBlockIO
Re-exports

Description

Abstract interface, types, and utilities.

Synopsis

data HasBlockIO m h = HasBlockIO {
- close :: HasCallStack => m ()
- submitIO :: HasCallStack => Vector (IOOp (PrimState m) h) -> m (Vector IOResult)
- hSetNoCache :: Handle h -> Bool -> m ()
- hAdvise :: Handle h -> FileOffset -> FileOffset -> Advice -> m ()
- hAllocate :: Handle h -> FileOffset -> FileOffset -> m ()
- tryLockFile :: FsPath -> LockMode -> m (Maybe (LockFileHandle m))
- hSynchronise :: Handle h -> m ()
- synchroniseDirectory :: FsPath -> m ()
- createHardLink :: FsPath -> FsPath -> m ()
}
data IOOp s h
- = IOOpRead !(Handle h) !FileOffset !(MutableByteArray s) !BufferOffset !ByteCount
- | IOOpWrite !(Handle h) !FileOffset !(MutableByteArray s) !BufferOffset !ByteCount
ioopHandle :: IOOp s h -> Handle h
ioopFileOffset :: IOOp s h -> FileOffset
ioopBuffer :: IOOp s h -> MutableByteArray s
ioopBufferOffset :: IOOp s h -> BufferOffset
ioopByteCount :: IOOp s h -> ByteCount
newtype IOResult = IOResult ByteCount
data Advice
- = AdviceNormal
- | AdviceRandom
- | AdviceSequential
- | AdviceWillNeed
- | AdviceDontNeed
- | AdviceNoReuse
hAdviseAll :: HasBlockIO m h -> Handle h -> Advice -> m ()
hDropCacheAll :: HasBlockIO m h -> Handle h -> m ()
data LockMode
- = SharedLock
- | ExclusiveLock
data FileLockingNotSupported = FileLockingNotSupported
newtype LockFileHandle m = LockFileHandle {
- hUnlock :: m ()
}
synchroniseFile :: MonadThrow m => HasFS m h -> HasBlockIO m h -> FsPath -> m ()
synchroniseDirectoryRecursive :: MonadThrow m => HasFS m h -> HasBlockIO m h -> FsPath -> m ()
type ByteCount = CSize
type FileOffset = COff

HasBlockIO

data HasBlockIO m h Source #

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.

Constructors

HasBlockIO

Fields

close :: HasCallStack => m ()
(Idempotent) close the IO context that is required for running submitIO.
Using submitIO after close throws an FsError exception.
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.
The buffers in the IOOps should be pinned memory. If any buffer is unpinned memory, an FsError exception will be thrown.
hSetNoCache :: Handle h -> Bool -> m ()
Set the file data caching mode for a file handle.
hAdvise :: Handle h -> FileOffset -> FileOffset -> Advice -> m ()
Predeclare an access pattern for file data.
hAllocate :: Handle h -> FileOffset -> FileOffset -> m ()
Allocate file space.
tryLockFile :: FsPath -> LockMode -> m (Maybe (LockFileHandle m))
Try to acquire a file lock without blocking.
This function throws FileLockingNotSupported when file locking is not supported.
hSynchronise :: Handle h -> m ()
Synchronise file contents with the storage device.
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.
synchroniseDirectory :: FsPath -> m ()
Synchronise a directory with the storage device.
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.
createHardLink :: FsPath -> FsPath -> m ()
Create a hard link for an existing file at the source path and a new file at the target path.

Instances

Instances details

NFData (HasBlockIO m h) Source #
Instance details Defined in System.FS.BlockIO.API Methods rnf :: HasBlockIO m h -> () #

data IOOp s h Source #

Constructors

IOOpRead !(Handle h) !FileOffset !(MutableByteArray s) !BufferOffset !ByteCount
IOOpWrite !(Handle h) !FileOffset !(MutableByteArray s) !BufferOffset !ByteCount

Instances

Instances details

NFData (IOOp s h) Source #
Instance details Defined in System.FS.BlockIO.API Methods rnf :: IOOp s h -> () #

ioopHandle :: IOOp s h -> Handle h Source #

ioopFileOffset :: IOOp s h -> FileOffset Source #

ioopBuffer :: IOOp s h -> MutableByteArray s Source #

ioopBufferOffset :: IOOp s h -> BufferOffset Source #

ioopByteCount :: IOOp s h -> ByteCount Source #

newtype IOResult Source #

Number of read/written bytes.

Constructors

IOResult ByteCount

Instances

Instances details

Show IOResult Source #
Instance details Defined in System.FS.BlockIO.API Methods showsPrec :: Int -> IOResult -> ShowS # show :: IOResult -> String # showList :: [IOResult] -> ShowS #
Eq IOResult Source #
Instance details Defined in System.FS.BlockIO.API Methods (==) :: IOResult -> IOResult -> Bool # (/=) :: IOResult -> IOResult -> Bool #
Prim IOResult Source #
Instance details Defined in System.FS.BlockIO.API Methods sizeOfType# :: Proxy IOResult -> Int# Source # sizeOf# :: IOResult -> Int# Source # alignmentOfType# :: Proxy IOResult -> Int# Source # alignment# :: IOResult -> Int# Source # indexByteArray# :: ByteArray# -> Int# -> IOResult Source # readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, IOResult #) Source # writeByteArray# :: MutableByteArray# s -> Int# -> IOResult -> State# s -> State# s Source # setByteArray# :: MutableByteArray# s -> Int# -> Int# -> IOResult -> State# s -> State# s Source # indexOffAddr# :: Addr# -> Int# -> IOResult Source # readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, IOResult #) Source # writeOffAddr# :: Addr# -> Int# -> IOResult -> State# s -> State# s Source # setOffAddr# :: Addr# -> Int# -> Int# -> IOResult -> State# s -> State# s Source #
Unbox IOResult Source #
Instance details Defined in System.FS.BlockIO.API
Vector Vector IOResult Source #
Instance details Defined in System.FS.BlockIO.API Methods basicUnsafeFreeze :: Mutable Vector s IOResult -> ST s (Vector IOResult) Source # basicUnsafeThaw :: Vector IOResult -> ST s (Mutable Vector s IOResult) Source # basicLength :: Vector IOResult -> Int Source # basicUnsafeSlice :: Int -> Int -> Vector IOResult -> Vector IOResult Source # basicUnsafeIndexM :: Vector IOResult -> Int -> Box IOResult Source # basicUnsafeCopy :: Mutable Vector s IOResult -> Vector IOResult -> ST s () Source # elemseq :: Vector IOResult -> IOResult -> b -> b Source #
MVector MVector IOResult Source #
Instance details Defined in System.FS.BlockIO.API Methods basicLength :: MVector s IOResult -> Int Source # basicUnsafeSlice :: Int -> Int -> MVector s IOResult -> MVector s IOResult Source # basicOverlaps :: MVector s IOResult -> MVector s IOResult -> Bool Source # basicUnsafeNew :: Int -> ST s (MVector s IOResult) Source # basicInitialize :: MVector s IOResult -> ST s () Source # basicUnsafeReplicate :: Int -> IOResult -> ST s (MVector s IOResult) Source # basicUnsafeRead :: MVector s IOResult -> Int -> ST s IOResult Source # basicUnsafeWrite :: MVector s IOResult -> Int -> IOResult -> ST s () Source # basicClear :: MVector s IOResult -> ST s () Source # basicSet :: MVector s IOResult -> IOResult -> ST s () Source # basicUnsafeCopy :: MVector s IOResult -> MVector s IOResult -> ST s () Source # basicUnsafeMove :: MVector s IOResult -> MVector s IOResult -> ST s () Source # basicUnsafeGrow :: MVector s IOResult -> Int -> ST s (MVector s IOResult) Source #
newtype Vector IOResult Source #
Instance details Defined in System.FS.BlockIO.API newtype Vector IOResult = V_IOResult (Vector IOResult)
newtype MVector s IOResult Source #
Instance details Defined in System.FS.BlockIO.API newtype MVector s IOResult = MV_IOResult (MVector s IOResult)

Advice

data Advice Source #

Copy of System.Posix.Fcntl.Advice from the unix package

Constructors

AdviceNormal
AdviceRandom
AdviceSequential
AdviceWillNeed
AdviceDontNeed
AdviceNoReuse

Instances

Instances details

Show Advice Source #
Instance details Defined in System.FS.BlockIO.API Methods showsPrec :: Int -> Advice -> ShowS # show :: Advice -> String # showList :: [Advice] -> ShowS #
Eq Advice Source #
Instance details Defined in System.FS.BlockIO.API Methods (==) :: Advice -> Advice -> Bool # (/=) :: Advice -> Advice -> Bool #

hAdviseAll :: HasBlockIO m h -> Handle h -> Advice -> m () Source #

Apply Advice to all bytes of a file, which is referenced by a Handle.

hDropCacheAll :: HasBlockIO m h -> Handle h -> m () Source #

Drop the full file referenced by a Handle from the OS page cache, if present.

File locks

data LockMode #

Indicates a mode in which a file should be locked.

Constructors

SharedLock
ExclusiveLock

data FileLockingNotSupported #

Exception thrown by hLock on non-Windows platforms that don't support flock.

Since: base-4.10.0.0

Constructors

FileLockingNotSupported

Instances

Instances details

Exception FileLockingNotSupported
Instance details Defined in GHC.IO.Handle.Lock.Common Methods toException :: FileLockingNotSupported -> SomeException # fromException :: SomeException -> Maybe FileLockingNotSupported # displayException :: FileLockingNotSupported -> String #
Show FileLockingNotSupported	Since: base-4.10.0.0
Instance details Defined in GHC.IO.Handle.Lock.Common Methods showsPrec :: Int -> FileLockingNotSupported -> ShowS # show :: FileLockingNotSupported -> String # showList :: [FileLockingNotSupported] -> ShowS #

newtype LockFileHandle m Source #

A handle to a file locked using tryLockFile.

Constructors

LockFileHandle
Fields hUnlock :: m () Release a file lock acquired using `tryLockFile`.

Storage synchronisation

synchroniseFile :: MonadThrow m => HasFS m h -> HasBlockIO m h -> FsPath -> m () Source #

Synchronise a file's contents and metadata with the storage device.

synchroniseDirectoryRecursive :: MonadThrow m => HasFS m h -> HasBlockIO m h -> FsPath -> m () Source #

Synchronise a directory's contents and metadata with the storage device, and recursively for all entries in the directory.

Re-exports

type ByteCount = CSize #

type FileOffset = COff #