filelock-0.1.1.8: Portable interface to file locking (flock / LockFileEx)

Safe Haskell | Safe-Inferred
Language | Haskell2010

System.FileLock

Description

This module provides a portable interface to file locks as a mechanism for inter-process synchronization.

Each file lock is associated with a file. When taking a lock, the assiciated file is created if it's not present, then the file is locked in an OS-dependent way. While the lock is being held, no other process or thread can take it, unless the specified `SharedExclusive` values allow it.

All locks held by a process are released when the process exits. They can also be explicitly released using `unlockFile`.

It is not recommended to open or otherwise use lock files for other purposes, because it tends to expose differences between operating systems. For example, on Windows `openFile` for a lock file will fail when the lock is held, but on Unix it won't.

Note on the implementation: currently the module uses flock(2) on non-Windows platforms, and LockFileEx on Windows.

On non-Windows platforms, `InterruptibleFFI` is used in the implementation to ensures that blocking lock calls can be correctly interrupted by async exceptions (e.g. functions like `timeout`). This has been tested on Linux.

Synopsis

- data FileLock
- data SharedExclusive
  - = Shared
  - | Exclusive
- lockFile :: FilePath -> SharedExclusive -> IO FileLock
- tryLockFile :: FilePath -> SharedExclusive -> IO (Maybe FileLock)
- unlockFile :: FileLock -> IO ()
- withFileLock :: FilePath -> SharedExclusive -> (FileLock -> IO a) -> IO a
- withTryFileLock :: FilePath -> SharedExclusive -> (FileLock -> IO a) -> IO (Maybe a)

# Documentation

data FileLock Source #

A token that represents ownership of a lock.

#### Instances

Instances details

Eq FileLock Source # |
Instance details Defined in System.FileLock Methods (==) :: FileLock -> FileLock -> Bool Source # (/=) :: FileLock -> FileLock -> Bool Source #

data SharedExclusive Source #

A type of lock to be taken.

Constructors

Shared | Other process can hold a shared lock at the same time.
Exclusive | No other process can hold a lock, shared or exclusive.

#### Instances

Instances details

Show SharedExclusive Source # |
Instance details Defined in System.FileLock Methods showsPrec :: Int -> SharedExclusive -> ShowS Source # show :: SharedExclusive -> String Source # showList :: [SharedExclusive] -> ShowS Source #
Eq SharedExclusive Source # |
Instance details Defined in System.FileLock Methods (==) :: SharedExclusive -> SharedExclusive -> Bool Source # (/=) :: SharedExclusive -> SharedExclusive -> Bool Source #

lockFile :: FilePath -> SharedExclusive -> IO FileLock Source #

Take a lock. This function blocks until the lock is available.

tryLockFile :: FilePath -> SharedExclusive -> IO (Maybe FileLock) Source #

Try to take a lock. This function does not block. If the lock is not immediately available, it returns Nothing.

unlockFile :: FileLock -> IO () Source #

Release the lock.

withFileLock :: FilePath -> SharedExclusive -> (FileLock -> IO a) -> IO a Source #

Perform some action with a lock held. Blocks until the lock is available.

withTryFileLock :: FilePath -> SharedExclusive -> (FileLock -> IO a) -> IO (Maybe a) Source #

Perform some action with a lock held. Non-blocking.