gi-glib-2.0.30: 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.Once

Contents

- Exported types
- Methods
  - initEnter
  - initEnterImpl
  - initEnterPointer
  - initLeave
  - initLeavePointer
- Properties
  - retval
  - status

Description

A `Once` struct controls a one-time initialization function. Any one-time initialization function must have its own unique `Once` struct.

Since: 2.4

Synopsis

- newtype Once = Once (ManagedPtr Once)
- newZeroOnce :: MonadIO m => m Once
- onceInitEnter :: (HasCallStack, MonadIO m) => Ptr () -> m (Bool, Ptr ())
- onceInitEnterImpl :: (HasCallStack, MonadIO m) => CSize -> m Bool
- onceInitEnterPointer :: (HasCallStack, MonadIO m) => Ptr () -> m Bool
- onceInitLeave :: (HasCallStack, MonadIO m) => Ptr () -> CSize -> m (Ptr ())
- onceInitLeavePointer :: (HasCallStack, MonadIO m) => Ptr () -> Ptr () -> m ()
- clearOnceRetval :: MonadIO m => Once -> m ()
- getOnceRetval :: MonadIO m => Once -> m (Ptr ())
- setOnceRetval :: MonadIO m => Once -> Ptr () -> m ()
- getOnceStatus :: MonadIO m => Once -> m OnceStatus
- setOnceStatus :: MonadIO m => Once -> OnceStatus -> m ()

# Exported types

newtype Once Source #

Memory-managed wrapper type.

Constructors

Once (ManagedPtr Once) |

#### Instances

Instances details

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

newZeroOnce :: MonadIO m => m Once Source #

Construct a `Once` struct initialized to zero.

# Methods

## initEnter

onceInitEnter Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `location`: location of a static initializable variable containing 0
-> m (Bool, Ptr ()) | Returns: `True` if the initialization section should be entered, `False` and blocks otherwise

Function to be called when starting a critical initialization section. The argument `location` must point to a static 0-initialized variable that will be set to a value other than 0 at the end of the initialization section. In combination with `onceInitLeave` and the unique address `valueLocation`, it can be ensured that an initialization section will be executed only once during a program's life time, and that concurrent threads are blocked until initialization completed. To be used in constructs like this:

### C code

     static gsize initialization_value = 0;

     if (g_once_init_enter (&initialization_value))
       {
         gsize setup_value = 42; // initialization code here

         g_once_init_leave (&initialization_value, setup_value);
       }

     // use initialization_value here

While `location` has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`.

Since: 2.14

## initEnterImpl

onceInitEnterImpl :: (HasCallStack, MonadIO m) => CSize -> m Bool Source #

No description available in the introspection data.

## initEnterPointer

onceInitEnterPointer Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `location`: location of a static initializable variable containing `NULL`
-> m Bool | Returns: `True` if the initialization section should be entered, `False` and blocks otherwise

This functions behaves in the same way as `onceInitEnter`, but can can be used to initialize pointers (or `guintptr`) instead of `gsize`.

### C code

     static MyStruct *interesting_struct = NULL;

     if (g_once_init_enter_pointer (&interesting_struct))
       {
         MyStruct *setup_value = allocate_my_struct (); // initialization code here

         g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value));
       }

     // use interesting_struct here

Since: 2.80

## initLeave

onceInitLeave Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `location`: location of a static initializable variable containing 0
-> CSize | `result`: new non-0 value for *`valueLocation`
-> m (Ptr ()) |

Counterpart to `onceInitEnter`. Expects a location of a static 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in `onceInitEnter` on this initialization variable.

While `location` has a `volatile` qualifier, this is a historical artifact and the pointer passed to it should not be `volatile`.

Since: 2.14

## initLeavePointer

onceInitLeavePointer Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Ptr () | `location`: location of a static initializable variable containing `NULL`
-> Ptr () | `result`: new non-`NULL` value for `*location`
-> m () |

Counterpart to `onceInitEnterPointer`. Expects a location of a static `NULL`-initialized initialization variable, and an initialization value other than `NULL`. Sets the variable to the initialization value, and releases concurrent threads blocking in `onceInitEnterPointer` on this initialization variable.

This functions behaves in the same way as `onceInitLeave`, but can be used to initialize pointers (or `guintptr`) instead of `gsize`.

Since: 2.80

# Properties

## retval

the value returned by the call to the function, if `status` is `OnceStatusReady`

clearOnceRetval :: MonadIO m => Once -> m () Source #

Set the value of the “`retval`” field to `Nothing`. When overloading is enabled, this is equivalent to

    clear #retval

getOnceRetval :: MonadIO m => Once -> m (Ptr ()) Source #

Get the value of the “`retval`” field. When overloading is enabled, this is equivalent to

    get once #retval

setOnceRetval :: MonadIO m => Once -> Ptr () -> m () Source #

Set the value of the “`retval`” field. When overloading is enabled, this is equivalent to

    set once [ #retval := value ]

## status

the status of the `Once`

getOnceStatus :: MonadIO m => Once -> m OnceStatus Source #

Get the value of the “`status`” field. When overloading is enabled, this is equivalent to

    get once #status

setOnceStatus :: MonadIO m => Once -> OnceStatus -> m () Source #

Set the value of the “`status`” field. When overloading is enabled, this is equivalent to

    set once [ #status := value ]