gi-glib-2.0.29: GLib bindings

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

GI.GLib.Structs.Cond

Contents

- Exported types
- Methods
  - broadcast
  - clear
  - init
  - signal
  - wait
  - waitUntil

Description

The `Cond` struct is an opaque data structure that represents a condition. Threads can block on a `Cond` if they find a certain condition to be false. If other threads change the state of this condition they signal the `Cond`, and that causes the waiting threads to be woken up.

Consider the following example of a shared variable. One or more threads can wait for data to be published to the variable and when another thread publishes the data, it can signal one of the waiting threads to wake up to collect the data.

Here is an example for using GCond to block a thread until a condition is satisfied:

### C code

     gpointer current_data = NULL;
     GMutex data_mutex;
     GCond data_cond;

     void
     push_data (gpointer data)
     {
       g_mutex_lock (&data_mutex);
       current_data = data;
       g_cond_signal (&data_cond);
       g_mutex_unlock (&data_mutex);
     }

     gpointer
     pop_data (void)
     {
       gpointer data;

       g_mutex_lock (&data_mutex);
       while (!current_data)
         g_cond_wait (&data_cond, &data_mutex);
       data = current_data;
       current_data = NULL;
       g_mutex_unlock (&data_mutex);

       return data;
     }

Whenever a thread calls `pop_data()` now, it will wait until current_data is non-`Nothing`, i.e. until some other thread has called `push_data()`.

The example shows that use of a condition variable must always be paired with a mutex. Without the use of a mutex, there would be a race between the check of `currentData` by the while loop in `pop_data()` and waiting. Specifically, another thread could set `currentData` after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep. `Cond` is specifically useful for its ability to release the mutex and go to sleep atomically.

It is also important to use the `condWait` and `condWaitUntil` functions only inside a loop which checks for the condition to be true. See `condWait` for an explanation of why the condition may not be true even after it returns.

If a `Cond` is allocated in static storage then it can be used without initialisation. Otherwise, you should call `condInit` on it and `condClear` when done.

A `Cond` should only be accessed via the g_cond_ functions.

Synopsis

- newtype Cond = Cond (ManagedPtr Cond)
- newZeroCond :: MonadIO m => m Cond
- condBroadcast :: (HasCallStack, MonadIO m) => Cond -> m ()
- condClear :: (HasCallStack, MonadIO m) => Cond -> m ()
- condInit :: (HasCallStack, MonadIO m) => Cond -> m ()
- condSignal :: (HasCallStack, MonadIO m) => Cond -> m ()
- condWait :: (HasCallStack, MonadIO m) => Cond -> Mutex -> m ()
- condWaitUntil :: (HasCallStack, MonadIO m) => Cond -> Mutex -> Int64 -> m Bool

# Exported types

newtype Cond Source #

Memory-managed wrapper type.

Constructors

Cond (ManagedPtr Cond) |

#### Instances

Instances details

Eq Cond Source # |
Instance details Defined in GI.GLib.Structs.Cond Methods (==) :: Cond -> Cond -> Bool Source # (/=) :: Cond -> Cond -> Bool Source #
BoxedPtr Cond Source # |
Instance details Defined in GI.GLib.Structs.Cond Methods boxedPtrCopy :: Cond -> IO Cond Source # boxedPtrFree :: Cond -> IO () Source #
CallocPtr Cond Source # |
Instance details Defined in GI.GLib.Structs.Cond Methods boxedPtrCalloc :: IO (Ptr Cond) Source #
ManagedPtrNewtype Cond Source # |
Instance details Defined in GI.GLib.Structs.Cond Methods toManagedPtr :: Cond -> ManagedPtr Cond Source #
tag ~ 'AttrSet => Constructible Cond tag Source # |
Instance details Defined in GI.GLib.Structs.Cond Methods new :: MonadIO m => (ManagedPtr Cond -> Cond) -> [AttrOp Cond tag] -> m Cond Source #

newZeroCond :: MonadIO m => m Cond Source #

Construct a `Cond` struct initialized to zero.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

broadcast, clear, init, signal, wait, waitUntil.

#### Getters

None.

#### Setters

None.

## broadcast

condBroadcast Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: a `Cond`
-> m () |

If threads are waiting for `cond`, all of them are unblocked. If no threads are waiting for `cond`, this function has no effect. It is good practice to lock the same mutex as the waiting threads while calling this function, though not required.

## clear

condClear Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: an initialised `Cond`
-> m () |

Frees the resources allocated to a `Cond` with `condInit`.

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

Calling `condClear` for a `Cond` on which threads are blocking leads to undefined behaviour.

Since: 2.32

## init

condInit Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: an uninitialized `Cond`
-> m () |

Initialises a `Cond` so that it can be used.

This function is useful to initialise a `Cond` that has been allocated as part of a larger structure. It is not necessary to initialise a `Cond` that has been statically allocated.

To undo the effect of `condInit` when a `Cond` is no longer needed, use `condClear`.

Calling `condInit` on an already-initialised `Cond` leads to undefined behaviour.

Since: 2.32

## signal

condSignal Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: a `Cond`
-> m () |

If threads are waiting for `cond`, at least one of them is unblocked. If no threads are waiting for `cond`, this function has no effect. It is good practice to hold the same lock as the waiting thread while calling this function, though not required.

## wait

condWait Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: a `Cond`
-> Mutex | `mutex`: a `Mutex` that is currently locked
-> m () |

Atomically releases `mutex` and waits until `cond` is signalled. When this function returns, `mutex` is locked again and owned by the calling thread.

When using condition variables, it is possible that a spurious wakeup may occur (ie: `condWait` returns even though `condSignal` was not called). It's also possible that a stolen wakeup may occur. This is when `condSignal` is called, but another thread acquires `mutex` before this thread and modifies the state of the program in such a way that when `condWait` is able to return, the expected condition is no longer met.

For this reason, `condWait` must always be used in a loop. See the documentation for `Cond` for a complete example.

## waitUntil

condWaitUntil Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Cond | `cond`: a `Cond`
-> Mutex | `mutex`: a `Mutex` that is currently locked
-> Int64 | `endTime`: the monotonic time to wait until
-> m Bool | Returns: `True` on a signal, `False` on a timeout

Waits until either `cond` is signalled or `endTime` has passed.

As with `condWait` it is possible that a spurious or stolen wakeup could occur. For that reason, waiting on a condition variable should always be in a loop, based on an explicitly-checked predicate.

`True` is returned if the condition variable was signalled (or in the case of a spurious wakeup). `False` is returned if `endTime` has passed.

The following code shows how to correctly perform a timed wait on a condition variable (extending the example presented in the documentation for `Cond`):

### C code

    gpointer
    pop_data_timed (void)
    {
      gint64 end_time;
      gpointer data;

      g_mutex_lock (&data_mutex);

      end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
      while (!current_data)
        if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
          {
            // timeout has passed.
            g_mutex_unlock (&data_mutex);
            return NULL;
          }

      // there is data for us
      data = current_data;
      current_data = NULL;

      g_mutex_unlock (&data_mutex);

      return data;
    }

Notice that the end time is calculated once, before entering the loop and reused. This is the motivation behind the use of absolute time on this API -- if a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again (which would lead to a total wait time of more than 5 seconds).

Since: 2.32