-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Shared memory and control structures for IPC -- -- Provides portable shared memory allocator and some synchronization -- primitives. Can be used for interprocess communication. Refer to -- README.md for further information. @package interprocess @version 0.2.1.0 -- | Exposed internals of SharedObjectName. module Foreign.SharedObjectName.Internal -- | Reference to a shared object; can be sent to other processes. newtype SOName a SOName :: ForeignPtr CChar -> SOName a -- | Write a shared object name into somwhere referenced by a handle. -- Useful for sending references to other processes via pipes. hPutSOName :: Handle -> SOName a -> IO () -- | Read a shared object name from somwhere referenced by a handle. -- Returns Nothing if hGetBuf gets less than -- 32 bytes. Useful for sending references to other processes -- via pipes. hGetSOName :: Handle -> IO (Maybe (SOName a)) -- | Use a pointer to a C string to pass to some low-level (e.g. foreign) -- functions. SOName is asserted immutable, so do not modify it! unsafeWithSOName :: SOName a -> (CString -> IO b) -> IO b -- | Generate a new unique shared object name. genSOName :: IO (SOName a) -- | Allocate a new shared object name. newEmptySOName :: IO (SOName a) instance GHC.Show.Show (Foreign.SharedObjectName.Internal.SOName a) instance GHC.Read.Read (Foreign.SharedObjectName.Internal.SOName a) instance GHC.Classes.Eq (Foreign.SharedObjectName.Internal.SOName a) instance GHC.Classes.Ord (Foreign.SharedObjectName.Internal.SOName a) instance Foreign.Storable.Storable (Foreign.SharedObjectName.Internal.SOName a) -- | Globally unique names to be used as references in the interprocess -- communication. -- -- The implementation must guarantee that no two processes can generate -- the same unique SOName independently at the same time. To -- ensure this, the implementation uses three different seeds: -- --
    --
  1. C rand() with a time-dependent seed -- srand(time(NULL))
    2. --
  2. Process id taken from getpid or -- GetCurrentProcessId (unique across process).
    3. --
  3. A global auto-incremented variable (unique within a process).
    4. --
module Foreign.SharedObjectName -- | Reference to a shared object; can be sent to other processes. data SOName a -- | Write a shared object name into somwhere referenced by a handle. -- Useful for sending references to other processes via pipes. hPutSOName :: Handle -> SOName a -> IO () -- | Read a shared object name from somwhere referenced by a handle. -- Returns Nothing if hGetBuf gets less than -- 32 bytes. Useful for sending references to other processes -- via pipes. hGetSOName :: Handle -> IO (Maybe (SOName a)) -- | Use a pointer to a C string to pass to some low-level (e.g. foreign) -- functions. SOName is asserted immutable, so do not modify it! unsafeWithSOName :: SOName a -> (CString -> IO b) -> IO b -- | This module is an adaptation of MVar to an interprocess -- communication (IPC). The IPC setting implies a few changes to the -- interface. -- --
    --
  1. StoredMVar resides in a shared memory region.
    2. --
  2. We use Storable instance to serialize and deserialize a -- value.
    3. --
  3. Point (2) implies the value is always fully evaluated before being -- stored.
    4. --
  4. Scheduling is done by OS, thus the module does not guarantee FIFO -- order.
    5. --
  5. Using StoredMVar is only safe if Storable instance -- for its content is correct and peek does not throw exceptions. -- If peek throws an exception inside takeMVar or -- swapMVar, the original content of StoredMVar is not -- restored
    6. --
module Control.Concurrent.Process.StoredMVar -- | An StoredMVar is a synchronising variable, used for -- communication between concurrent processes or threads. It can be -- thought of as a a box, which may be empty or full. -- -- StoredMVar tries to mimic vanilla MVar, though it -- behaves quite differently. It uses Storable instance to make -- the value accessible in different memory spaces. Thus, the content of -- StoredMVar is forced to be fully evaluated and serialized. data StoredMVar a -- | Get a global reference to the StoredMVar. Send this reference -- to another process to lookup this StoredMVar and start -- interprocess communication. mVarName :: StoredMVar a -> SOName (StoredMVar a) -- | Create a StoredMVar which is initially empty. newEmptyMVar :: forall a. Storable a => IO (StoredMVar a) -- | Create a StoredMVar which is initially empty. newMVar :: Storable a => a -> IO (StoredMVar a) -- | Find a StoredMVar created in another process ot thread by its -- reference. lookupMVar :: Storable a => SOName (StoredMVar a) -> IO (StoredMVar a) -- | Return the contents of the StoredMVar. If the StoredMVar -- is currently empty, takeMVar will wait until it is full. After -- a takeMVar, the StoredMVar is left empty. -- -- takeMVar :: Storable a => StoredMVar a -> IO a -- | Put a value into an StoredMVar. If the StoredMVar is -- currently full, putMVar will wait until it becomes empty. -- -- putMVar :: Storable a => StoredMVar a -> a -> IO () -- | Atomically read the contents of an StoredMVar. If the -- StoredMVar is currently empty, readMVar will wait until -- its full. readMVar is guaranteed to receive the next -- putMVar. -- -- readMVar is multiple-wakeup, so when multiple readers are -- blocked on an StoredMVar, all of them are woken up at the same -- time. readMVar :: Storable a => StoredMVar a -> IO a -- | Atomically take a value from an StoredMVar, put a new value -- into the StoredMVar and return the value taken. swapMVar :: Storable a => StoredMVar a -> a -> IO a -- | A non-blocking version of takeMVar. The tryTakeMVar -- function returns immediately, with Nothing if the -- StoredMVar was empty, or Just a if the -- StoredMVar was full with contents a. After -- tryTakeMVar, the StoredMVar is left empty. tryTakeMVar :: Storable a => StoredMVar a -> IO (Maybe a) -- | A non-blocking version of putMVar. The tryPutMVar -- function attempts to put the value a into the -- StoredMVar, returning True if it was successful, or -- False otherwise. tryPutMVar :: Storable a => StoredMVar a -> a -> IO Bool -- | A non-blocking version of readMVar. The tryReadMVar -- function returns immediately, with Nothing if the -- StoredMVar was empty, or Just a if the -- StoredMVar was full with contents a. tryReadMVar :: Storable a => StoredMVar a -> IO (Maybe a) -- | A non-blocking version of swapMVar. Atomically attempt take a -- value from an StoredMVar, put a new value into the -- StoredMVar and return the value taken (thus, leave the -- StoredMVar full). Return Nothing if the -- StoredMVar was empty (and leave it empty). trySwapMVar :: Storable a => StoredMVar a -> a -> IO (Maybe a) -- | Check whether a given StoredMVar is empty. -- -- Notice that the boolean value returned is just a snapshot of the state -- of the MVar. By the time you get to react on its result, the MVar may -- have been filled (or emptied) - so be extremely careful when using -- this operation. Use tryTakeMVar instead if possible. isEmptyMVar :: StoredMVar a -> IO Bool -- | withMVar is an exception-safe wrapper for operating on the -- contents of an StoredMVar. This operation is exception-safe: it -- will replace the original contents of the StoredMVar if an -- exception is raised (see Control.Exception). However, it is -- only atomic if there are no other producers for this -- StoredMVar. withMVar :: Storable a => StoredMVar a -> (a -> IO b) -> IO b -- | Like withMVar, but the IO action in the second -- argument is executed with asynchronous exceptions masked. withMVarMasked :: Storable a => StoredMVar a -> (a -> IO b) -> IO b -- | A slight variation on modifyMVar_ that allows a value to be -- returned (b) in addition to the modified value of the -- StoredMVar. modifyMVar :: Storable a => StoredMVar a -> (a -> IO (a, b)) -> IO b -- | An exception-safe wrapper for modifying the contents of an -- StoredMVar. Like withMVar, modifyMVar will -- replace the original contents of the StoredMVar if an exception -- is raised during the operation. This function is only atomic if there -- are no other producers for this StoredMVar. modifyMVar_ :: Storable a => StoredMVar a -> (a -> IO a) -> IO () -- | Like modifyMVar, but the IO action in the second -- argument is executed with asynchronous exceptions masked. modifyMVarMasked :: Storable a => StoredMVar a -> (a -> IO (a, b)) -> IO b -- | Like modifyMVar_, but the IO action in the second -- argument is executed with asynchronous exceptions masked. modifyMVarMasked_ :: Storable a => StoredMVar a -> (a -> IO a) -> IO () instance GHC.Classes.Eq (Control.Concurrent.Process.StoredMVar.StoredMVar a) -- | Simple interprocess quantity semaphores -- -- Based on POSIX or Win32 C semaphores module Control.Concurrent.Process.QSem -- | QSem is a quantity semaphore in which the resource is aqcuired -- and released in units of one. data QSem -- | Build a new QSem with a supplied initial quantity. The initial -- quantity must be at least 0. -- -- This function throws an exception if an underlying platform-dependent -- function fails. newQSem :: Int -> IO QSem -- | Lookup QSem by its name in the global namespace. Use this function to -- init several entangled semaphores in different processes. -- -- This function throws an exception if no QSem with this name -- exist, or if an underlying platform-dependent function fails. lookupQSem :: SOName QSem -> IO QSem -- | Wait for a unit to become available -- -- This function throws an exception if an underlying platform-dependent -- function fails. waitQSem :: QSem -> IO () -- | Try to take a unit of the QSem. -- -- This function does not wait, in fact. Sorry for naming. -- -- Returns: -- -- -- -- This function does not throw an exception. tryWaitQSem :: QSem -> IO Bool -- | Signal that a unit of the QSem is available -- -- This function throws an exception if an underlying platform-dependent -- function fails. signalQSem :: QSem -> IO () -- | Get a global reference to the semaphore. Send this reference to -- another process to lookup this semaphore and start interprocess -- communication. qSemName :: QSem -> SOName QSem instance GHC.Classes.Eq Control.Concurrent.Process.QSem.QSem module Foreign.SharedPtr.C -- | Special pointer format to pass between memory spaces of processes. data SharedPtr a -- | Opaque pointer to the allocator type defined in C code. type Allocator = Ptr AllocatorT -- | C structure, should not be inspected from Haskell code data AllocatorT c'shared_createAllocator :: IO Allocator c'shared_lookupAllocator :: CString -> IO Allocator c'shared_destroyAllocator :: Allocator -> IO () c'shared_getStoreName :: Allocator -> CString c'shared_ptrToShPtr :: Allocator -> Ptr a -> SharedPtr a c'shared_shPtrToPtr :: Allocator -> SharedPtr a -> Ptr a c'shared_malloc :: Allocator -> CSize -> IO (Ptr a) c'shared_realloc :: Allocator -> Ptr a -> CSize -> IO (Ptr a) c'shared_free :: Allocator -> Ptr a -> IO () p'shared_createAllocator :: FunPtr (IO Allocator) p'shared_lookupAllocator :: FunPtr (CString -> IO Allocator) p'shared_destroyAllocator :: FunPtr (Allocator -> IO ()) p'shared_getStoreName :: FunPtr (Allocator -> CString) p'shared_ptrToShPtr :: FunPtr (Allocator -> Ptr a -> SharedPtr a) p'shared_shPtrToPtr :: FunPtr (Allocator -> SharedPtr a -> Ptr a) p'shared_malloc :: FunPtr (Allocator -> CSize -> IO (Ptr a)) p'shared_realloc :: FunPtr (Allocator -> Ptr a -> CSize -> IO (Ptr a)) p'shared_free :: FunPtr (Allocator -> Ptr a -> IO ()) p'vk_shared_malloc :: FunPtr (Ptr Void -> CSize -> CSize -> allocScope -> IO (Ptr Void)) p'vk_shared_realloc :: FunPtr (Ptr Void -> Ptr Void -> CSize -> CSize -> allocScope -> IO (Ptr Void)) p'vk_shared_free :: FunPtr (Ptr Void -> Ptr Void -> IO ()) instance Foreign.Storable.Storable (Foreign.SharedPtr.C.SharedPtr a) instance GHC.Generics.Generic (Foreign.SharedPtr.C.SharedPtr a) instance Data.Data.Data a => Data.Data.Data (Foreign.SharedPtr.C.SharedPtr a) instance GHC.Show.Show (Foreign.SharedPtr.C.SharedPtr a) instance GHC.Classes.Ord (Foreign.SharedPtr.C.SharedPtr a) instance GHC.Classes.Eq (Foreign.SharedPtr.C.SharedPtr a) module Foreign.SharedPtr -- | Special pointer format to pass between memory spaces of processes. data SharedPtr a -- | Make a portable shared pointer out of a regular pointer. The result -- can be transfered to another process and re-created using the shared -- Allocator. toSharedPtr :: Allocator -> Ptr a -> SharedPtr a -- | Reconstruct a regular pointer from a portable shared pointer. Returns -- NULL if shared pointer or allocator are not valid. fromSharedPtr :: Allocator -> SharedPtr a -> Ptr a -- | Opaque pointer to the allocator type defined in C code. type Allocator = Ptr AllocatorT -- | Create a new Allocator. createAllocator :: IO Allocator -- | Lookup a Allocator by its name. Use this to share one allocator -- between multiple processes. lookupAllocator :: SOName Allocator -> IO Allocator -- | Destroy allocator instance. Note: memory is fully unlinked and -- released only after the last allocator sharing the memory is -- destroyed. destroyAllocator :: Allocator -> IO () withNewAllocator :: (Allocator -> IO a) -> IO a withAllocator :: SOName Allocator -> (Allocator -> IO a) -> IO a allocStoreName :: Allocator -> SOName Allocator malloc :: Storable a => Allocator -> IO (Ptr a) mallocBytes :: Allocator -> Int -> IO (Ptr a) realloc :: Allocator -> Ptr a -> Int -> IO (Ptr a) free :: Allocator -> Ptr a -> IO ()