gi-glib-2.0.24: GLib bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GLib.Unions.Mutex

Contents

- Exported types
- Methods
  - Overloaded methods
  - clear
  - init
  - lock
  - trylock
  - unlock

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
- 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

Instances details

Eq Mutex Source # |
Instance details Defined in GI.GLib.Unions.Mutex Methods (==) :: Mutex -> Mutex -> Bool # (/=) :: Mutex -> Mutex -> Bool #
ManagedPtrNewtype Mutex Source # |
Instance details Defined in GI.GLib.Unions.Mutex Methods toManagedPtr :: Mutex -> ManagedPtr Mutex Source #
BoxedPtr Mutex Source # |
Instance details Defined in GI.GLib.Unions.Mutex Methods boxedPtrCopy :: Mutex -> IO Mutex Source # boxedPtrFree :: Mutex -> IO () Source #
CallocPtr Mutex Source # |
Instance details Defined in GI.GLib.Unions.Mutex Methods boxedPtrCalloc :: IO (Ptr Mutex) Source #
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 Source #

newZeroMutex :: MonadIO m => m Mutex Source #

Construct a `Mutex` struct initialized to zero.

# Methods

## Overloaded 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.