filelock-0.1.1.2: 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.

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 #

A token that represents ownership of a lock.

#### Instances

Instances details

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

data SharedExclusive #

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

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

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

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

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

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

unlockFile :: FileLock -> IO () #

Release the lock.

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

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

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

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