-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | File locking
--   
--   This package provides access to platform dependent file locking APIs:
--   
--   
--   
- Open file descriptor locking on Linux
--   (Lukko.OFD)
--   
- BSD-style flock(2) locks on UNIX platforms
--   (Lukko.FLock)
--   
- Windows locking via LockFileEx (Lukko.Windows)
--   
- No-op locking, which throws exceptions (Lukko.NoOp)
--   
- Lukko module exports the best option for the target
--   platform with uniform API.
--   
--   
--   There are alternative file locking packages:
--   
--   
--   
- GHC.IO.Handle.Lock in base >= 4.10 is good
--   enough for most use cases. However, uses only Handles so these
--   locks cannot be used for intra-process locking. (You should use e.g.
--   MVar in addition).
--   
- filelock doesn't support OFD locking.
--   
--   
--   Lukko means lock in Finnish.
--   
--   Submodules Lukko.OFD, Lukko.Windows etc are available
--   based on following conditions.
--   
--   
--   if os(windows)
--     cpp-options: -DHAS_WINDOWS_LOCK
--   
--   elif (os(linux) && flag(ofd-locking))
--     cpp-options: -DHAS_OFD_LOCKING
--     cpp-options: -DHAS_FLOCK
--   
--   elif !(os(solaris) || os(aix))
--     cpp-options: -DHAS_FLOCK
--   
--   
--   Lukko.FLock is available on not (Windows or Solaris or AIX).
--   Lukko.NoOp is always available.
@package lukko
@version 0.1.2

-- | File locking via BSD-style flock(2).
module Lukko.FLock

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

-- | A constants specifying whether file locking is supported.
fileLockingSupported :: Bool

-- | A type level fileLockingSupported.
type FileLockingSupported = 'True

-- | Potentially availble lock methods.
data FileLockingMethod

-- | open file descriptor locking
MethodOFD :: FileLockingMethod

-- | BSD flock
MethodFLock :: FileLockingMethod

-- | Windows locking
MethodWindows :: FileLockingMethod

-- | No-Op (throws FileLockingNotSupported)
MethodNoOp :: FileLockingMethod

-- | A constant specifying this method
fileLockingMethod :: FileLockingMethod

-- | Indicates a mode in which a file should be locked.
data LockMode
SharedLock :: LockMode
ExclusiveLock :: LockMode

-- | Opaque file descriptor
--   
--   This is a wrapper over CInt
data FD

-- | Open file to be used for locking.
--   
--   
--   open(path, O_RDWR | O_CREAT);
--   
fdOpen :: FilePath -> IO FD

-- | Close lock file.
--   
--   
--   close(fd);
--   
fdClose :: FD -> IO ()

-- | Lock using BSD-style locks.
fdLock :: FD -> LockMode -> IO ()

-- | Try to lock using BSD-style locks.
fdTryLock :: FD -> LockMode -> IO Bool

-- | Unlock using BSD-style locks.
fdUnlock :: FD -> IO ()

-- | Lock using BSD-style locks.
hLock :: Handle -> LockMode -> IO ()

-- | Try to lock using BSD-style locks.
hTryLock :: Handle -> LockMode -> IO Bool

-- | Unlock using BSD-style locks.
hUnlock :: Handle -> IO ()

-- | Non-operating locks.
--   
--   All functions throw FileLockingNotImplemented.
module Lukko.NoOp

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

-- | A constants specifying whether file locking is supported.
fileLockingSupported :: Bool

-- | A type level fileLockingSupported.
type FileLockingSupported = 'False

-- | Potentially availble lock methods.
data FileLockingMethod

-- | open file descriptor locking
MethodOFD :: FileLockingMethod

-- | BSD flock
MethodFLock :: FileLockingMethod

-- | Windows locking
MethodWindows :: FileLockingMethod

-- | No-Op (throws FileLockingNotSupported)
MethodNoOp :: FileLockingMethod

-- | A constant specifying this method
fileLockingMethod :: FileLockingMethod

-- | Indicates a mode in which a file should be locked.
data LockMode
SharedLock :: LockMode
ExclusiveLock :: LockMode

-- | Opaque file descriptor
--   
--   This is a wrapper over CInt
data FD

-- | Open file to be used for locking.
--   
--   
--   open(path, O_RDWR | O_CREAT);
--   
fdOpen :: FilePath -> IO FD

-- | Close lock file.
--   
--   
--   close(fd);
--   
fdClose :: FD -> IO ()

-- | No-op implementation.
fdLock :: FD -> LockMode -> IO ()

-- | No-op implementation
fdTryLock :: FD -> LockMode -> IO Bool

-- | No-op implementation.
fdUnlock :: FD -> IO ()

-- | No-op implementation.
hLock :: Handle -> LockMode -> IO ()

-- | No-op implementation
hTryLock :: Handle -> LockMode -> IO Bool

-- | No-op implementation.
hUnlock :: Handle -> IO ()

-- | Linux open file descriptor locking.
--   
--   
--   https://www.gnu.org/software/libc/manual/html_node/Open-File-Description-Locks.html
--   
--   We prefer this over BSD locking (e.g. flock) since the latter appears
--   to break in some NFS configurations. Note that we intentionally do not
--   try to use ordinary POSIX file locking due to its peculiar semantics
--   under multi-threaded environments.
module Lukko.OFD

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

-- | A constants specifying whether file locking is supported.
fileLockingSupported :: Bool

-- | A type level fileLockingSupported.
type FileLockingSupported = 'True

-- | Potentially availble lock methods.
data FileLockingMethod

-- | open file descriptor locking
MethodOFD :: FileLockingMethod

-- | BSD flock
MethodFLock :: FileLockingMethod

-- | Windows locking
MethodWindows :: FileLockingMethod

-- | No-Op (throws FileLockingNotSupported)
MethodNoOp :: FileLockingMethod

-- | A constant specifying this method
fileLockingMethod :: FileLockingMethod

-- | Indicates a mode in which a file should be locked.
data LockMode
SharedLock :: LockMode
ExclusiveLock :: LockMode

-- | Opaque file descriptor
--   
--   This is a wrapper over CInt
data FD

-- | Open file to be used for locking.
--   
--   
--   open(path, O_RDWR | O_CREAT);
--   
fdOpen :: FilePath -> IO FD

-- | Close lock file.
--   
--   
--   close(fd);
--   
fdClose :: FD -> IO ()

-- | Lock using OFD locks.
fdLock :: FD -> LockMode -> IO ()

-- | Try to lock using OFD locks.
fdTryLock :: FD -> LockMode -> IO Bool

-- | Unlock using OFD locks.
fdUnlock :: FD -> IO ()

-- | Lock using OFD locks.
hLock :: Handle -> LockMode -> IO ()

-- | Try to lock using OFD locks.
hTryLock :: Handle -> LockMode -> IO Bool

-- | Unlock using OFD locks.
hUnlock :: Handle -> IO ()
instance GHC.Internal.Foreign.Storable.Storable Lukko.OFD.FLock

-- | Open Handle based locking
module Lukko

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

-- | A constants specifying whether file locking is supported.
fileLockingSupported :: Bool

-- | A type level fileLockingSupported.
type FileLockingSupported = 'True

-- | Potentially availble lock methods.
data FileLockingMethod

-- | open file descriptor locking
MethodOFD :: FileLockingMethod

-- | BSD flock
MethodFLock :: FileLockingMethod

-- | Windows locking
MethodWindows :: FileLockingMethod

-- | No-Op (throws FileLockingNotSupported)
MethodNoOp :: FileLockingMethod

-- | A constant specifying this method
fileLockingMethod :: FileLockingMethod

-- | Indicates a mode in which a file should be locked.
data LockMode
SharedLock :: LockMode
ExclusiveLock :: LockMode

-- | Opaque file descriptor
--   
--   An int / CInt on unix systems, and HANDLE
--   on windows.
type FD = FD

-- | Open file to be used for locking.
fdOpen :: FilePath -> IO FD

-- | Close lock file.
fdClose :: FD -> IO ()

-- | Like hLock, but work on "raw" file descriptor, as handled by
--   fdOpen and fdClose.
fdLock :: FD -> LockMode -> IO ()

-- | Non-blocking version of fdLock.
fdTryLock :: FD -> LockMode -> IO Bool

-- | Release a lock taken with fdLock or fdTryLock.
fdUnlock :: FD -> IO ()

-- | Convert GHC Handle to lukko FD.
handleToFd :: Handle -> IO FD

-- | If a Handle references a file descriptor, attempt to lock
--   contents of the underlying file in appropriate mode. If the file is
--   already locked in incompatible mode, this function blocks until the
--   lock is established. The lock is automatically released upon closing a
--   Handle.
--   
--   Things to be aware of:
--   
--   1) This function may block inside a C call. If it does, in order to be
--   able to interrupt it with asynchronous exceptions and/or for other
--   threads to continue working, you MUST use threaded version of the
--   runtime system.
--   
--   2) The implementation uses LockFileEx on Windows, open
--   file descriptor locks on Linux, and flock otherwise,
--   hence all of their caveats also apply here.
--   
--   3) On non-Windows plaftorms that don't support flock (e.g.
--   Solaris) this function throws FileLockingNotImplemented. We
--   deliberately choose to not provide fcntl based locking
--   instead because of its broken semantics.
hLock :: Handle -> LockMode -> IO ()

-- | Non-blocking version of hLock.
hTryLock :: Handle -> LockMode -> IO Bool

-- | Release a lock taken with hLock or hTryLock.
hUnlock :: Handle -> IO ()
