from .flags import Flags as flags

from .descriptors import Descriptors as descriptors

import time

from threading import (

Lock,

Event,

Thread,

)

from functools import wraps

import libcommon

class Trigger:

"""Trigger progress mechanism.

Provides simultaneous, controlled activation of functions at specified

time or interval in order to streamline program's progression.

Attributes

----------

_interval_trigger_activation : int, float

Trigger's pre-active duration.

_interval_trigger : int, float

Trigger's active duration.

_interval_min : int, float

Minimum duration before next trigger can run.

_interval_max : int, float

Duration after which max exceed event is fired.

_interval_critical : int, float

Duration after which critical exceed event is fired.

_interval_trigger_auto_add : int, float

Duration after which a new trigger is queued if no trigger exists.

_retries_trigger_auto_add : int

Number of retries for auto trigger queuing before firing error event.

_clock_interval : int, float

Duration after which clock is updated.

_clock_step : int, float

Amount by which clock is updated.

_interval_exceed_action_min : int

Exceed action for min interval exceed.

_interval_exceed_action_max : int

Exceed action for max interval exceed.

_interval_exceed_action_critical : int

Exceed action for critical interval exceed.

_list_notification : dict

List of callbacks registered for notification.

_list_blocking : dict

List of identifiers holding block for next trigger event.

_list_waiting : list

List of identifiers waiting for next trigger event.

_mode : int

Current execution mode.

_mode_next : int, NoneType

Next execution mode, to be activated on switch.

_active : bool

System's state.

_trigger_event : int

Active event for trigger.

_trigger_event_time : float

Instantaneous time at last event for trigger.

_trigger_event_description : str

Description for active event for trigger.

_lock_list_notification : Lock

Concurrency lock for _list_notification.

_lock_list_blocking : Lock

Concurrency lock for _list_blocking.

_lock_list_waiting : Lock

Concurrency lock for _list_waiting.

_lock_notify : Lock

Concurrency lock for _nofify.

_lock_trigger : Lock

Concurrency lock for _trigger.

_lock_trigger_event : Lock

Concurrency lock for _trigger_event.

_lock_error : Lock

Concurrency lock for _error.

_lock_mode : Lock

Concurrency lock for _mode.

_event_trigger_activation : Event

Concurrent event variable for pre-active trigger.

_event_trigger_trigger : Event

Concurrent event variable for active trigger.

_event_trigger_pre_min_force : Event

Concurrent event variable for pre-min force for trigger.

_event_trigger_pre_min_flush : Event

Concurrent event variable for pre-min flush for trigger.

_event_interval_trigger : Event

Concurrent event variable for trigger.

_event_interval_trigger_force : Event

Concurrent event variable for trigger force.

_event_interval_trigger_flush : Event

Concurrent event variable for trigger flush.

_event_clock_reset : Event

Concurrent event variable for clock reset.

_thread_trigger : Thread

Thread of last active trigger.

_thread_clock : Thread

Thread of active clock.

_clock_time : int, float

Current system time (elapsed) since last trigger.

_clock_active : bool

Clock's state.

_error_error : bool

Active errors.

_error_raisable : bool

Active raisable errors.

_error_time : int, float

Instantaneous time at last error.

_error_description : str

Description of active errors.

_error_values : dict

Active custom description for errors.

Methods

-------

__init__ (mode, **intervals, **clock_resolution, **exceed_actions)

Init trigger system with specified configurations.

state ()

Interact with system's state.

mode ()

Interact with system's operation mode.

notification_alert ()

Handles registration for event based notfications.

trigger_bind ()

Binds functions to system for automated execution, threading capable.

_trigger_bind ()

Binds functions to system for automated execution.

_trigger_bind_execute ()

Execute function with trigger operations.

wait ()

Wait for next trigger event to occur.

block ()

Add a block preventing next trigger event, until released.

release ()

Release the block for next trigger event.

notify ()

Send a manual notification alert to all registered receivers.

trigger_force ()

Force activate next trigger, overriding active blocks.

trigger_flush ()

Flush queued triggers.

trigger ()

Manually enqueue a trigger.

"""

def __init__ (

self,

mode = flags.MODE_NONE,

interval_trigger_activation = 0.1,

interval_trigger = 0.2,

interval_min = 1,

interval_max = 4,

interval_critical = 10,

interval_trigger_auto_add = 20,

retries_trigger_auto_add = 3,

clock_interval = 0.2,

clock_step = 0.2,

interval_exceed_action_min = flags.INTERVAL_EXCEED_ACTION_IGNORE,

interval_exceed_action_max = flags.INTERVAL_EXCEED_ACTION_NOTIFY,

interval_exceed_action_critical = (

flags.INTERVAL_EXCEED_ACTION_NOTIFY

| flags.INTERVAL_EXCEED_ACTION_ERROR_RAISE

| flags.INTERVAL_EXCEED_ACTION_HALT

),

debug_log = False,

debug_trace = True,

):

"""Init trigger system with specified configurations.

Parameters

----------

mode : int, default=flags.MODE_NONE

Mode to queue for next activation.

interval_trigger_activation : int, float, default=0.1

Trigger's pre-active duration.

interval_trigger : int, float, default=0.4

Trigger's active duration.

interval_min : int, float, default=1.0

Minimum duration before next trigger can run.

interval_max : int, float, default=4.0

Duration after which max exceed event is fired.

interval_critical : int, float, default=10

Duration after which critical exceed event is fired.

interval_trigger_auto_add : int, float, default=20

Duration after which a new trigger is queued if no trigger exists.

retries_trigger_auto_add : int, default=3

Number of retries for auto trigger queuing before firing error event.

clock_interval : int, float, default=0.2

Duration after which clock is updated.

clock_step : int, float, default=0.2

Amount by which clock is updated.

interval_exceed_action_min : int, default=IGNORE

Exceed action for min interval exceed.

interval_exceed_action_max : int, default=NOTIFY

Exceed action for max interval exceed.

interval_exceed_action_critical : int, default=(IGNORE|NOTIFY|HALT)

Exceed action for critical interval exceed.

Raises

------

Exception

* Non positive intervals.

* Non increasing intervals.

"""

self._interval_trigger_activation = abs(float(

interval_trigger_activation

))

self._interval_trigger = abs(float(interval_trigger))

self._interval_min = abs(float(interval_min))

self._interval_max = abs(float(interval_max))

self._interval_critical = abs(float(interval_critical))

self._interval_trigger_auto_add = abs(float(

interval_trigger_auto_add

))

self._retries_trigger_auto_add = abs(int(

retries_trigger_auto_add

))

self._clock_interval = abs(float(clock_interval))

self._clock_step = abs(float(clock_step))

if (not (

0

< self._interval_trigger_activation

<= self._interval_trigger

)):

raise Exception((

'{0}::\n'

+ 'interval_trigger_activation: {1}\n'

+ 'interval_trigger : {2}\n'

).format(

descriptors.ERROR_INTERVALS_NOT_MONOTONIC,

self._interval_trigger_activation,

self._interval_trigger,

))

elif (not (

0

< self._interval_trigger_activation

<= self._interval_min

<= self._interval_max

<= self._interval_critical

<= self._interval_trigger_auto_add

)):

raise Exception((

'{0}::\n'

+ 'interval_trigger_activation: {0}\n'

+ 'interval_min : {1}\n'

+ 'interval_max : {2}\n'

+ 'interval_critical : {3}\n'

+ 'interval_trigger_auto_add : {4}\n'

).format(

descriptors.ERROR_INTERVALS_NOT_MONOTONIC,

self._interval_trigger_activation,

self._interval_min,

self._interval_max,

self._interval_critical,

self._interval_trigger_auto_add,

))

elif (not (

0

<= self._retries_trigger_auto_add

)):

raise Exception((

'{0}::\n'

+ 'retries_trigger_auto_add: {1}\n'

).format(

descriptors.ERROR_RETRIES_TRIGGER_AUTO_ADD_INVALID,

self._retries_trigger_auto_add,

))

elif (not (

0

<= self._clock_interval

)):

raise Exception((

'{0}::\n'

+ 'clock_interval: {0}\n'

).format(

descriptors.ERROR_CLOCK_INTERVAL_INVALID,

self._clock_interval,

))

elif (not (

0

< self._clock_step

)):

raise Exception((

'{0}::\n'

+ 'clock_step: {0}\n'

).format(

descriptors.ERROR_CLOCK_STEP_INVALID,

self._clock_step,

))

self._interval_exceed_action_min = interval_exceed_action_min

self._interval_exceed_action_max = interval_exceed_action_max

self._interval_exceed_action_critical = interval_exceed_action_critical

self._list_notification = dict() # {

# id: [

# events,

# times, # -1 : ULD

# callback,

# ],

# }

self._list_blocking = dict() # {

# id: times_retain

# # -1 : ULD

# }

self._list_waiting = list() # [

# id,

# id,

# ]

if (mode not in (

flags.MODE_NONE,

flags.MODE_AUTO,

flags.MODE_MANUAL,

flags.MODE_HYBRID,

)):

mode = flags.MODE_NONE

self._mode = flags.MODE_NONE

self._mode_next = mode

self._active = False

self._trigger_event = flags.INTERVAL_EVENT_NONE

self._trigger_event_time = 0.0

self._trigger_event_description = descriptors.INTERVAL_EVENT_NONE

self._lock_list_notification = Lock()

self._lock_list_blocking = Lock()

self._lock_list_waiting = Lock()

self._lock_notify = Lock()

self._lock_trigger = Lock()

self._lock_trigger_event = Lock()

self._lock_error = Lock()

self._lock_mode = Lock()

self._lock_debug_log = Lock()

self._lock_debug_trace = Lock()

self._event_trigger_activation = Event()

self._event_trigger_trigger = Event()

self._event_trigger_pre_min_force = Event()

self._event_trigger_pre_min_flush = Event()

self._event_interval_trigger = Event()

self._event_interval_trigger_force = Event()

self._event_interval_trigger_flush = Event()

self._event_clock_reset = Event()

self._debug_allow_log = bool(debug_log)

self._debug_allow_trace = bool(debug_trace)

self._debug_data_log = list() # [

# trace,

# trace,

# ]

self._debug_data_trace = dict() # {

# originator:

# trace,

# }

self._debug_data_origin_tracker = dict() # {

# originator: [

# log.index,

# log.index,

# ],

# }

self._debug_notify = None

self._debug_trigger = None

self._thread_trigger = None

self._thread_clock = None

self._clock_time = 0.0

self._clock_active = False

self._error_error = False

self._error_raisable = False

self._error_time = 0.0

self._error_description = ''

self._error_values = dict()

'''

INFO: [plan]

trigger:

trigger_activation.set()

# thread: wait_1() -> granted

time.sleep(interval_trigger)

trigger_activation.clear()

# thread: wait_1() -> blocked

trigger.set()

# thread: wait_2() -> granted

clock.reset()

# clock: reset & resume

time.sleep(interval_trigger_activation)

trigger.clear()

thread:

task:

wait:

wait_1()

wait_2()

block()

work

release()

task:

wait:

wait_1() -> blocked until next trigger

issue.previous:

code:

if (trigger.enabled())

# trigger_id = 1

# trigger_time_left = 0.2

work1()

if (trigger.enabled())

# trigger_id = 1

# trigger_time_left = 0.01

work2()

if (trigger.enabled())

# trigger_id = 2

# trigger_time_left = 0.0

work3()

# blocked until next trigger

issue:

multiple triggers achieved due to:

* short exec time

* trigger enabled for long duration

ideal:

* only 1 trigger per wait

* not < 1

* not > 1

* prevent spill to next trigger

resolution_requirement:

* only 1 wait() should guarantee next / ongoing trigger

* block all wait() for next trigger

* allow all wait() for current trigger

* wait() should be a one-time mechanism, not to be called

multiple times

'''

def _identifier_validate (

self,

identifier = None,

required = True,

force_use = False,

regenerate = False,

list_validation = [],

owner = None,

):

"""Validates and/or regerates identifiers as required.

Parameters

----------

identifier : str, NoneType, default=None

Custom identifier to use, else auto-generate.

required : bool, default=True

Is identifier required for process ? If not, bypass process.

regenerate : bool, default=False

Allow identifier regeneration upon in-validity of supplied one.

force_use : bool, default=False

Force use supplied identifier even if in-valid, overriding existing.

list_validation : tuple, list, default=[]

List to utilize for checking uniqueness with.

owner : str, NoneType, default=None

Owner for regenerated identifier, else auto-generate as anonymous.

Returns

-------

tuple

Returns tuple containing supplied or new identifier and validity.

"""

if (not required):

return (identifier, True)

regenerate_identity = False

if (identifier in list_validation):

if (regenerate):

regenerate_identity = True

elif (force_use):

regenerate_identity = False

else:

return (identifier, False)

if ((not identifier) or (regenerate_identity)):

identifier = libcommon.identifier.generate(

owner=(owner or (

'libprogress.trigger[{0}].anonymous'.format(

self,

)

)),

)

return (identifier, True)

def state (

self,

activate = None,

reactivate = None,

non_blocking = False,

thread_timeout = None,

errors = False,

errors_raise = False,

describe = True,

):

"""Interact with system's state.

Parameters

----------

activate : bool, NoneType, default=None

Set True or False to activate or deactivate system.

reactivate : bool, NoneType, default=None

Set True to re-activate system.

non_blocking : bool, default=False

Run current interaction in non-blocking mode ?

thread_timeout : int, float, NoneType, default=None

Thread timeout if running in blocking mode.

errors : bool, default=False

Surface active errors ?

errors_raise : bool, default=False

Surface active errors along with raisable ones ?

describe : bool, default=True

Describe system state using descriptors ?

Raises

------

Exception

Exceptions are raised if errors or errors_raise is set, if occurred.

Returns

-------

str

Returns description of system's active state.

bool

Returns system's active state, else True on normal run.

"""

error_raisable = None

if (errors or errors_raise):

error_raisable = self._errors(

finalize = True,

return_raisable = errors_raise,

)

if (activate is not None):

self.mode(

activate = bool(activate),

)

error_raisable = self._errors(

finalize = True,

return_raisable = errors_raise,

)

elif (reactivate):

mode = self.modes()

self.mode(

activate = False,

non_blocking = non_blocking,

thread_timeout = thread_timeout,

)

error_raisable = self._errors(

finalize = True,

return_raisable = errors_raise,

)

self.mode(

mode = mode,

activate = True,

non_blocking = non_blocking,

thread_timeout = thread_timeout,

)

elif (errors or errors_raise):

if (error_raisable is not None):

raise (error_raisable)

else:

active = self._active

if (describe):

active = (

descriptors.STATE_ACTIVE

if (active)

else

descriptors.STATE_INACTIVE

)

return active

if (error_raisable is not None):

raise (error_raisable)

return True

def mode (

self,

mode = None,

activate = None,

non_blocking = False,

thread_timeout = None,

describe = True,

ignore_active = True,

):

"""Interact with system's operation mode.

Parameters

----------

mode : int, NoneType, default=None

Execution mode, either to activate or queue for next activation.

activate : bool, NoneType, default=None

Set True or False to activate or deactivate execution mode.

non_blocking : bool, default=False

Run current interaction in non-blocking mode ?

thread_timeout : int, float, NoneType, default=None

Thread timeout if running in blocking mode.

describe : bool, default=True

Describe system mode using descriptors ?

ignore_active : bool, default=True

Describe system's valid working mode, ignoring system's state.

Returns

-------

int

Returns system's currently active execution mode.

str

Returns description of system's currently active execution mode.

bool

Returns True on normal run.

"""

if (mode not in (

flags.MODE_NONE,

flags.MODE_AUTO,

flags.MODE_MANUAL,

flags.MODE_HYBRID,

)):

mode = None

if (mode is not None):

self._mode_next = mode

mode_thread = None

if (activate):

'''

if (

(mode is not None)

and (self._active)

):

'''

if (self._active):

'''

self.mode(

activate = False,

non_blocking = non_blocking,

thread_timeout = thread_timeout,

)

self._mode_next = mode

'''

Thread(

target = self._modes,

kwargs = {

'mode' : flags.MODE_NONE,

},

daemon = False,

).start()

mode_thread = Thread(

target = self._modes,

kwargs = {

'mode' : (mode or None), # self._mode_next,

},

daemon = False,

)

mode_thread.start()

elif (activate is False):

'''

if (mode is None):

self._mode_next = self._mode

elif (mode is not None):

self._mode_next = mode

'''

mode_thread = Thread(

target = self._modes,

kwargs = {

'mode' : flags.MODE_NONE,

},

daemon = False,

)

mode_thread.start()

else:

mode = self._mode

if (

ignore_active

and (not self._active)

):

mode = self._mode_next

if (describe):

if (mode == flags.MODE_NONE):

mode = descriptors.MODE_NONE

elif (mode == flags.MODE_AUTO):

mode = descriptors.MODE_AUTO

elif (mode == flags.MODE_MANUAL):

mode = descriptors.MODE_MANUAL

elif (mode == flags.MODE_HYBRID):

mode = descriptors.MODE_HYBRID

else:

mode = descriptors.MODE_SET_UNSET

elif (mode is None):

mode = flags.MODE_NONE

return mode

if (mode_thread):

if (not non_blocking):

mode_thread.join(timeout=thread_timeout)

return True

def _modes (

self,

mode=flags.MODE_NONE,

):

"""Switch system's operation mode.

Performs switch operation only if the target mode is not active.

Can only switch to/from MODE_NONE to any other mode.

Parameters

----------

mode : int, NoneType, default=flags.MODE_NONE

Execution mode, to switch to. Use None to switch to next queued mode.

Returns

-------

bool

Returns switch's success.

"""

self._lock_mode.acquire()

if (mode not in (

flags.MODE_NONE,

flags.MODE_AUTO,

flags.MODE_MANUAL,

flags.MODE_HYBRID,

)):

mode = None

if (mode is None):

mode = self._mode_next

try:

if (mode not in (

flags.MODE_NONE,

flags.MODE_AUTO,

flags.MODE_MANUAL,

flags.MODE_HYBRID,

)):

return False

elif (mode != self._mode):

if (mode == flags.MODE_NONE):

self._mode_next = self._mode

if (self._mode & flags.MODE_AUTO):

self._clock_active = False

self._event_trigger_pre_min_force.clear()

self._event_trigger_pre_min_flush.set()

self._event_interval_trigger_force.clear()

self._event_interval_trigger_flush.set()

try:

self._thread_clock.join()

except:

pass

try:

self._thread_trigger.join()

except:

pass

self._event_trigger_pre_min_flush.clear()

self._event_interval_trigger_flush.clear()

self._event_clock_reset.clear()

self._clock_time = 0.0

self._thread_clock = None

self._thread_trigger = None

if (self._mode & flags.MODE_MANUAL):

self._event_interval_trigger_force.clear()

self._event_interval_trigger_flush.set()

try:

self._thread_trigger.join()

except:

pass

self._event_interval_trigger_flush.clear()

self._thread_trigger = None

if (self._mode & flags.MODE_HYBRID):

pass

self._event_trigger_activation.clear()

self._event_trigger_trigger.clear()

self._event_trigger_pre_min_force.clear()

self._event_trigger_pre_min_flush.clear()

self._event_interval_trigger_force.clear()

self._event_interval_trigger_flush.clear()

self._event_interval_trigger.clear()

self._active = False

elif (self._mode != flags.MODE_NONE):

return False

elif (self._mode == flags.MODE_NONE):

self._errors(

reset = True,

)

self._trigger_events(

reset = True,

)

self._event_trigger_activation.clear()

self._event_trigger_trigger.clear()

self._event_trigger_pre_min_force.clear()

self._event_trigger_pre_min_flush.clear()

self._event_interval_trigger_force.clear()

self._event_interval_trigger_flush.clear()

self._event_interval_trigger.clear()

if (mode & flags.MODE_MANUAL):

self._thread_trigger = None

if (mode & flags.MODE_AUTO):

self._event_clock_reset.set()

self._clock_time = 0.0

self._clock_active = True

thread_clock = Thread(

target=self._clock_thread,

)

self._thread_clock = thread_clock

thread_clock.start()

self._event_trigger_pre_min_force.set()

if (mode & flags.MODE_HYBRID):

pass

self._event_interval_trigger_force.set()

self._active = True

self._mode = mode

finally:

self._lock_mode.release()

return True

def notification_alert (

self,

identifier = None,

callback = None,

unregister = False,

events = flags.INTERVAL_EVENT_ALL,

times = -1, # unlimited

identity_regenerate = False,

identity_force_use = False,

):

"""Handles registration for event based notfications.

Registers or un-registers for notification alert by appending or removing

details from notification list.

Parameters

----------

identifier : str, NoneType, default=None

Custom identifier to register callback with, else auto-generate.

callback : callable, NoneType, default=None

Callback, used upon alert generation.

unregister : bool, default=False

Unregister alert bound to callback with specified identifier.

events : int, default=flags.INTERVAL_EVENT_ALL

Events upon which notification alert is to be sent.

times : int, default=-1

Number of times to service alerts, upon expiry auto-unregister.

identity_regenerate : bool, default=False

Allow identifier regeneration upon in-validity of supplied one.

identity_force_use : bool, default=False

Force use supplied identifier even if in-valid, overriding existing.

Returns

-------

str

Returns identifier used upon successful registration.

bool

Returns success as bool on unregistration or registration, if failed.

"""

if (unregister):

if (not identifier):

return False

self._lock_list_notification.acquire()

try:

self._list_notification.pop(identifier)

except:

pass

finally:

self._lock_list_notification.release()

return True

elif ((not callback)

or (not callable(callback))

):

return False

elif (not times):

return False

else:

times = int(times)

identifier, proceed = self._identifier_validate(

identifier = identifier,

required = True,

force_use = identity_force_use,

regenerate = identity_regenerate,

list_validation = self._list_notification.keys(),

owner = (

'libprogress.trigger[{0}].notification_alert.anonymous'.format(

self,

)

),

)

if (not proceed):

return False

self._lock_list_notification.acquire()

try:

self._list_notification[identifier] = [

events,

times,

callback,

]

finally:

self._lock_list_notification.release()

return identifier

def trigger_bind (

self,

trigger_bound_function,

args = [],

kwargs = {},

identifier = None,

times_retain = -1,

times_recurse = -1,