:right-sidebar: True

Once
===================================================================

.. currentmodule:: gi.repository.GLib


.. versionadded:: 2.4




.. class:: Once(*args, **kwargs)
   :no-contents-entry:






A :obj:`~gi.repository.GLib.Once` struct controls a one-time initialization function. Any
one-time initialization function must have its own unique :obj:`~gi.repository.GLib.Once`
struct.




Methods
-------

.. rst-class:: interim-class

.. class:: Once
   :no-index:


   .. classmethod:: init_enter() -> ~typing.Tuple[bool, ~typing.Any]

      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
      :func:`~gi.repository.GLib.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:


      .. code-block:: C
          :dedent:

            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``\.


      .. versionadded:: 2.14








   .. classmethod:: init_enter_impl() -> bool

      









   .. classmethod:: init_enter_pointer() -> bool

      This functions behaves in the same way as :func:`~gi.repository.GLib.Once.init_enter`, but can
      can be used to initialize pointers (or :obj:`int`) instead of :obj:`~gi.repository.gsize`\.


      .. code-block:: C
          :dedent:

            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


      .. versionadded:: 2.80








   .. classmethod:: init_leave(result: int) -> ~typing.Any

      Counterpart to :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.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``\.


      .. versionadded:: 2.14





      :param result: new non-0 value for ``value_location``




   .. classmethod:: init_leave_pointer(result: ~typing.Any = None) -> None

      Counterpart to :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.Once.init_enter_pointer` on this
      initialization variable.

      This functions behaves in the same way as :func:`~gi.repository.GLib.Once.init_leave`, but
      can be used to initialize pointers (or :obj:`int`) instead of :obj:`~gi.repository.gsize`\.


      .. versionadded:: 2.80





      :param result: new non-``NULL`` value for ``*location``














Fields
------

.. rst-class:: interim-class

.. class:: Once
   :no-index:
   

   .. attribute:: retval

      The value returned by the call to the function, if ``status``
               is :const:`~gi.repository.GLib.OnceStatus.READY`






   .. attribute:: status

      The status of the :obj:`~gi.repository.GLib.Once`