System.IO.LockFile

Provide exclusive access to a resource using lock file.

Usage Example

Following example acquires lock file and then waits 1000000 micro seconds before releasing it. Note also that it is possible to specify retry strategy. Here we set it to No and therefore this code won't retry to acquire lock file after first failure.

module Main (main)
    where

import Control.Concurrent (threadDelay)
    -- From base package, but GHC specific.

import qualified Control.Monad.TaggedException as Exception (handle)
    -- From tagged-exception-core package.
    -- http://hackage.haskell.org/package/tagged-exception-core
import Data.Default.Class (Default(def))
    -- From data-default-class package, alternatively it's possible to use
    -- data-default package version 0.5.2 and above.
    -- http://hackage.haskell.org/package/data-default-class
    -- http://hackage.haskell.org/package/data-default
import System.IO.LockFile
    ( LockingParameters(retryToAcquireLock)
    , RetryStrategy(No)
    , withLockFile
    )


main :: IO ()
main = handleException
    . withLockFile lockParams lockFile $ threadDelay 1000000
  where
    lockParams = def
        { retryToAcquireLock = No
        }

    lockFile = "/var/run/lock/my-example-lock"

    handleException = Exception.handle
        $ putStrLn . ("Locking failed with: " ++) . show

This command line example shows that trying to execute two instances of example at the same time will result in failure of the second one.

$ ghc example.hs
[1 of 1] Compiling Main             ( example.hs, example.o )
Linking example ...
$ ./example & ./example
[1] 7893
Locking failed with: Unable to acquire lock file: "/var/run/lock/my-example-lock"
$ [1]+  Done                    ./example

Run computation with locked resource.

withLockFile

Arguments

:: (MonadMask m, MonadIO m)

=> LockingParameters

-> FilePath

Lock file name.

-> m a

-> Throws LockingException m a

Acquire a lock file before running computation and release it when it's done.

If "action" raises IOException then this is not wrapped by LockingException. Only IOException that occurred during locking or unlocking is mapped to LockingException. This doesn't affect the fact that lock file is removed even if "action" fails.

withLockFile_

Arguments

:: (MonadMask m, MonadIO m)

=> LockingParameters

-> FilePath

Lock file name.

-> m ()

-> Throws LockingException m ()

Type restricted version of withLockFile.

withLockFile'

Arguments

:: (MonadMask m, MonadIO m)

=> LockingParameters

-> FilePath

Lock file name.

-> m a

-> m a

Version of withLockFile that hides exception witness from its type signature.

Configuration

data LockingParameters

Locking algorithm parameters. When doubt, use def, otherwise start with it. Example:

lockedDo
    :: (MonadMask m, MonadIO m)
    => FilePath
    -> m a
    -> Throws LockingException m a
lockedDo = withLockFile lockParams lockFile
  where
    lockParams = def
        { retryToAcquireLock = NumberOfTimes 3
        }

    lockFile = withLockExt "/var/lock/my-app"

Constructors

LockingParameters

Fields

retryToAcquireLock :: !RetryStrategy

Strategy for handling situations when lock-file is already acquired.

sleepBetweenRetires :: !Word64

Sleep interval in microseconds.

Instances

Eq LockingParameters

Data LockingParameters

Read LockingParameters

Show LockingParameters

Generic LockingParameters

Default LockingParameters

Defined as:

def = LockingParameters
    { retryToAcquireLock  = def
    , sleepBetweenRetires = 8000000  -- 8 seconds
    }

Sleep interval is inspired by lockfile command line utility that is part of Procmail.

Typeable * LockingParameters

type Rep LockingParameters

data RetryStrategy

Defines strategy for handling situations when lock-file is already acquired.

Constructors

No

Don't retry at all.

Indefinitely

Retry indefinitely.

NumberOfTimes !Word8

Retry only specified number of times. If equal to zero then it is interpreted same way as No.

Instances

Eq RetryStrategy

Data RetryStrategy

Read RetryStrategy

Show RetryStrategy

Generic RetryStrategy

Default RetryStrategy

Defined as: def = Indefinitely

Typeable * RetryStrategy

type Rep RetryStrategy

Exceptions

data LockingException

Constructors

UnableToAcquireLockFile FilePath

Wasn't able to aquire lock file specified as an argument.

CaughtIOException IOException

IOException occurred while creating or removing lock file.

Instances

Show LockingException

Exception LockingException

HiddenException LockingException

Typeable * LockingException

Utility functions

withLockExt :: FilePath -> FilePath

Append default lock file extension. Useful e.g. for generating lock file name out of regular file name.