Once

Added in version 2.4.

class Once(*args, **kwargs)

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

Methods

class Once

init_enter() → tuple[bool, None]

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 init_leave() and the unique address value_location, 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:

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.

Added in version 2.14.

init_enter_impl(location: int) → bool

Parameters:: location

init_enter_pointer(location: None) → bool

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

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

Added in version 2.80.

Parameters:: location – location of a static initializable variable containing NULL

init_leave(result: int) → None

Counterpart to init_enter(). 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 init_enter() 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.

Added in version 2.14.

Parameters:: result – new non-0 value for *value_location

init_leave_pointer(location: None, result: None) → None

Counterpart to init_enter_pointer(). 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 init_enter_pointer() on this initialization variable.

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

Added in version 2.80.

Parameters:

location – location of a static initializable variable containing NULL
result – new non-NULL value for *location

Fields

class Once

retval: The value returned by the call to the function, if status is READY

status: The status of the Once