Skip to content

GLib.Once

record (struct)

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

Static functions

init_enter

@staticmethod
def init_enter(location: int) -> tuple[bool, int]

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

Parameters:

  • location — location of a static initializable variable containing 0

init_enter_impl

@staticmethod
def init_enter_impl(location: int) -> bool

init_enter_pointer

@staticmethod
def init_enter_pointer(location: int) -> bool

This functions behaves in the same way as Once.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

Parameters:

  • location — location of a static initializable variable containing NULL

init_leave

@staticmethod
def init_leave(location: int, result: int) -> int

Counterpart to Once.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 Once.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.

Parameters:

  • location — location of a static initializable variable containing 0
  • result — new non-0 value for *value_location

init_leave_pointer

@staticmethod
def init_leave_pointer(location: int, result: int | None = ...) -> None

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

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

Parameters:

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

Properties

status

status: OnceStatus | int  # read/write

retval

retval: int  # read/write