Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (inaki@blueleaf.cc)
Safe Haskell	None
Language	Haskell2010

GI.GLib.Unions.Mutex

Contents

Exported types
Methods

Description

The Mutex struct is an opaque data structure to represent a mutex (mutual exclusion). It can be used to protect data against shared access.

Take for example the following function:

C code

 int
 give_me_next_number (void)
 {
   static int current_number = 0;

   // now do a very complicated calculation to calculate the new
   // number, this might for example be a random number generator
   current_number = calc_next_number (current_number);

   return current_number;
 }

It is easy to see that this won't work in a multi-threaded application. There current_number must be protected against shared access. A Mutex can be used as a solution to this problem:

C code

 int
 give_me_next_number (void)
 {
   static GMutex mutex;
   static int current_number = 0;
   int ret_val;

   g_mutex_lock (&mutex);
   ret_val = current_number = calc_next_number (current_number);
   g_mutex_unlock (&mutex);

   return ret_val;
 }

Notice that the Mutex is not initialised to any particular value. Its placement in static storage ensures that it will be initialised to all-zeros, which is appropriate.

If a Mutex is placed in other contexts (eg: embedded in a struct) then it must be explicitly initialised using mutexInit.

A Mutex should only be accessed via g_mutex_ functions.

Synopsis

newtype Mutex = Mutex (ManagedPtr Mutex)
newZeroMutex :: MonadIO m => m Mutex
noMutex :: Maybe Mutex
mutexClear :: (HasCallStack, MonadIO m) => Mutex -> m ()
mutexInit :: (HasCallStack, MonadIO m) => Mutex -> m ()
mutexLock :: (HasCallStack, MonadIO m) => Mutex -> m ()
mutexTrylock :: (HasCallStack, MonadIO m) => Mutex -> m Bool
mutexUnlock :: (HasCallStack, MonadIO m) => Mutex -> m ()

Exported types

newtype Mutex Source #

Memory-managed wrapper type.

Constructors

Mutex (ManagedPtr Mutex)

Instances

WrappedPtr Mutex Source #
Instance details Defined in GI.GLib.Unions.Mutex Methods wrappedPtrCalloc :: IO (Ptr Mutex) # wrappedPtrCopy :: Mutex -> IO Mutex # wrappedPtrFree :: Maybe (GDestroyNotify Mutex) #
tag ~ AttrSet => Constructible Mutex tag Source #
Instance details Defined in GI.GLib.Unions.Mutex Methods new :: MonadIO m => (ManagedPtr Mutex -> Mutex) -> [AttrOp Mutex tag] -> m Mutex #

newZeroMutex :: MonadIO m => m Mutex Source #

Construct a Mutex struct initialized to zero.

noMutex :: Maybe Mutex Source #

A convenience alias for Nothing :: Maybe Mutex.

Methods

clear

mutexClear Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Mutex	`mutex`: an initialized `Mutex`
-> m ()

Frees the resources allocated to a mutex with mutexInit.

This function should not be used with a Mutex that has been statically allocated.

Calling mutexClear on a locked mutex leads to undefined behaviour.

Sine: 2.32

init

mutexInit Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Mutex	`mutex`: an uninitialized `Mutex`
-> m ()

Initializes a Mutex so that it can be used.

This function is useful to initialize a mutex that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialize a mutex that has been statically allocated.

C code

  typedef struct {
    GMutex m;
    ...
  } Blob;

Blob *b;

b = g_new (Blob, 1);
g_mutex_init (&b->m);

To undo the effect of mutexInit when a mutex is no longer needed, use mutexClear.

Calling mutexInit on an already initialized Mutex leads to undefined behaviour.

Since: 2.32

lock

mutexLock Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Mutex	`mutex`: a `Mutex`
-> m ()

Locks mutex. If mutex is already locked by another thread, the current thread will block until mutex is unlocked by the other thread.

Mutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling mutexLock on a Mutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks).

trylock

mutexTrylock Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Mutex	`mutex`: a `Mutex`
-> m Bool	Returns: `True` if `mutex` could be locked

Tries to lock mutex. If mutex is already locked by another thread, it immediately returns False. Otherwise it locks mutex and returns True.

Mutex is neither guaranteed to be recursive nor to be non-recursive. As such, calling mutexLock on a Mutex that has already been locked by the same thread results in undefined behaviour (including but not limited to deadlocks or arbitrary return values).

unlock

mutexUnlock Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Mutex	`mutex`: a `Mutex`
-> m ()

Unlocks mutex. If another thread is blocked in a mutexLock call for mutex, it will become unblocked and can lock mutex itself.

Calling mutexUnlock on a mutex that is not locked by the current thread leads to undefined behaviour.