bencher.variables.singleton_parametrized_sweep
==============================================

.. py:module:: bencher.variables.singleton_parametrized_sweep

.. autoapi-nested-parse::

   Singleton variant of ParametrizedSweep (thread-safe).

   Provides a per-subclass singleton with the smallest useful surface:

   - One instance per subclass via ``__new__``.
   - Base ``__init__`` calls the Parametrized chain exactly once.
   - ``init_singleton()`` returns a result that is **truthy on first call**
     (backward-compatible with ``if self.init_singleton():``) and also
     works as a **context manager** that auto-resets singleton state when
     the ``with`` block raises during first-time init.
   - ``reset_singleton()`` classmethod to manually clear singleton state.
   - All operations are **thread-safe** via an internal lock.

   Example (boolean style — unchanged from before)::

       class MySweep(ParametrizedSweepSingleton):
           def __init__(self, value=0):
               if self.init_singleton():
                   self.value = value  # only set once
               super().__init__()  # safe no-op after the first call

   Example (context-manager style — auto-resets on failure)::

       class MySweep(ParametrizedSweepSingleton):
           def __init__(self, **kwargs):
               with self.init_singleton() as is_first:
                   if is_first:
                       self._do_fallible_setup(**kwargs)
               super().__init__()



Classes
-------

.. autoapisummary::

   bencher.variables.singleton_parametrized_sweep._SingletonInitResult
   bencher.variables.singleton_parametrized_sweep.ParametrizedSweepSingleton


Module Contents
---------------

.. py:class:: _SingletonInitResult(cls, is_first: bool)

   Ephemeral result from ``init_singleton()``.

   * **Bool** — ``bool(result)`` is ``True`` when this is the first init.
   * **Context manager** — on ``__exit__``, if the block raised *and* this
     was the first init, singleton bookkeeping is rolled back via
     ``reset_singleton()`` so a subsequent construction can retry.


   .. py:attribute:: __slots__
      :value: ('_cls', '_is_first')



   .. py:attribute:: _cls


   .. py:attribute:: _is_first


   .. py:method:: __bool__() -> bool


   .. py:method:: __enter__()


   .. py:method:: __exit__(exc_type, exc_val, exc_tb)


.. py:class:: ParametrizedSweepSingleton(**params)

   Bases: :py:obj:`bencher.variables.parametrised_sweep.ParametrizedSweep`


   A minimal per-subclass singleton for ParametrizedSweep.

   - Repeated construction returns the same instance for each subclass.
   - Ensures the Parametrized ``__init__`` chain runs only once.
   - ``init_singleton()`` returns a result that is truthy once per subclass
     and doubles as a context manager for automatic rollback on failure.
   - ``reset_singleton()`` explicitly clears singleton state for a subclass.
   - Thread-safe: all shared state is protected by ``_lock``.


   .. py:attribute:: _instances


   .. py:attribute:: _seen


   .. py:attribute:: _lock


   .. py:attribute:: _singleton_inited
      :value: True



   .. py:method:: init_singleton() -> _SingletonInitResult
      :classmethod:


      Mark *cls* as seen and return a ``_SingletonInitResult``.

      The result is **truthy** the first time a subclass calls this and
      **falsy** on every subsequent call — identical to the previous boolean
      return value.

      It can also be used as a **context manager**::

          with self.init_singleton() as is_first:
              if is_first:
                  self._fallible_setup()

      If the ``with`` block raises during a first-time init, the singleton
      bookkeeping is rolled back so the next construction can retry cleanly.



   .. py:method:: reset_singleton() -> None
      :classmethod:


      Clear singleton state for *cls*, allowing re-initialisation.