BetterEvent

class privex.helpers.thread.BetterEvent(wait_on: str = 'set', name: str = None, default: bool = False, notify_set=True, notify_clear=True)

BetterEvent (alias InvertibleEvent) is a more flexible version of threading.Event, which adds many new capabilities / features on top of threading.Event:

• The wait_on constructor parameter allows you to choose what flag states that the standard wait() will trigger upon:

  • 'set' - the default - works like threading.Event, wait() only triggers when the event is in the “set” state, i.e. _flag is True

  • 'clear' - opposite of the default - works opposite to threading.Event, wait() only triggers when the event is in the “clear” state, i.e. _flag is False

  • 'both' - In the both setting, wait() will simply wait until _flag is changed, whether from set to clear, or clear to set. This wait_on setting only works as long as notify_set and notify_clear are set to True

• The default constructor parameter allows you to choose whether the event starts as “cleared” (False - default), or “set” (True), which is useful when using some of the alternative wait_on settings.

• New fail parameter for wait(), wait_set() and wait_clear() - when this is set to True, the method will raise EventWaitTimeout when the timeout is hit, instead of just returning False.

• New wait_set() method, this works like the classic threading.Event wait method - it’s only triggered when _flag is set to True (set) - no matter what wait_on setting is active.

• New wait_clear() method, this works opposite to the classic threading.Event wait method - it’s only triggered when _flag is set to False (cleared) - no matter what wait_on setting is active.

Example Usage

Below is a very simple thread class using SafeLoopThread which uses a BetterEvent so we can signal when it can start running, and when it’s allowed to restart itself:

>>> from privex.helpers import BetterEvent, SafeLoopThread
>>>
>>> class MyThread(SafeLoopThread):
...     def __init__(self, *args, trig, **kwargs):
...         self.trig = trig
...         super().__init__(*args, **kwargs)
...     def loop(self):
...         print("Waiting for trig to become set before doing stuff...")
...         self.trig.wait()   # Same behaviour as threading.Event.wait - waits for trig.set()
...         print("trig is set. doing stuff...")
...         print("finished doing stuff.")
...         print("Waiting for trig to become clear before restarting loop...")
...         self.trig.wait_clear()  # Unlike threading.Event, BetterEvent allows waiting for the "clear" signal
...
>>> evt = BetterEvent(name='My Event')
>>> t = MyThread(trig=evt)
>>> t.start()
Waiting for trig to become set before doing stuff...
>>> evt.set()   # We flip evt (trig) to "set", which notifies MyThread it can proceed.
trig is set. doing stuff...
finished doing stuff.
Waiting for trig to become clear before restarting loop...
>>> evt.clear()  # Unlike threading.Event, we can "clear" the event, and MyThread will detect the "clear" signal instantly.
Waiting for trig to become set before doing stuff...
>>> evt.set()    # The loop restarted. Now we can flip trig back to "set"
trig is set. doing stuff...
finished doing stuff.
Waiting for trig to become clear before restarting loop...

__init__(wait_on: str = 'set', name: str = None, default: bool = False, notify_set=True, notify_clear=True)

Parameters

• wait_on – set (default) - wait() triggers when event is “set”. clear - wait() triggers when event is “clear”. both - wait() triggers when the event state flips from “set” to “clear” or vice versa.

• name (str) – An optional name to identify this event

• default – The default state of the event. Either False for “clear”, or True for “set”

• notify_set – Whether to notify state listeners wait() wait_set() wait_clear() when set() is called and the state changes from “clear” to “set”

• notify_clear – Whether to notify state listeners wait() wait_set() wait_clear() when clear() is called and the state changes from “set” to “clear”

Methods

Methods

__init__([wait_on, name, default, …])	param wait_on set (default) - wait() triggers when event is “set”. clear - wait() triggers when
clear()	Reset the internal flag to false.
set()	Set the internal flag to true.
wait([timeout, fail])	Multi-purpose wait method which works similarly to threading.Event.wait() but with some extra features.
wait_clear([timeout, fail])	Wait until _flag is False
wait_set([timeout, fail])	Wait until _flag is True