pylablib.core.thread package

Submodules

pylablib.core.thread.callsync module

class pylablib.core.thread.callsync.QCallResultSynchronizer(skippable=True)[source]

Bases: QThreadNotifier

get_progress()[source]

Get the progress of the call execution.

Can be "waiting" (call is not done executing), "done" (call done successfully), "fail" (call failed, probably due to thread being stopped), "skip" (call was skipped), or "exception" (call raised an exception).

is_call_done()[source]

Check if the call is done

skipped()[source]

Check if the call was skipped

failed()[source]

Check if the call failed

get_value_sync(timeout=None, default=None, error_on_fail=True, error_on_skip=True, pass_exception=True)[source]

Wait (with the given timeout) for the value passed by the notifier

If error_on_fail==True and the controlled thread notifies of a fail (usually, if it’s stopped before it executed the call), raise threadprop.NoControllerThreadError; otherwise, return default. If error_on_skip==True and the call was skipped (e.g., due to full call queue), raise threadprop.SkippedCallError; otherwise, return default. If pass_exception==True and the returned value represents exception, re-raise it in the caller thread; otherwise, return default.

done_notify()

Check if notifying is done

done_wait()

Check if waiting is done

get_value()

Get the value passed by the notifier (doesn’t check if it has been passed already)

notify(*args, **kwargs)

Notify the waiting process.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called before wait(), return immediately.

notifying_state()
success_wait()

Check if waiting is done successfully

wait(*args, **kwargs)

Wait for the notification.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called after notify(), return immediately.

waiting()

Check if waiting is in progress

waiting_state()
class pylablib.core.thread.callsync.QDummyResultSynchronizer[source]

Bases: object

Dummy result synchronizer for call which don’t require result synchronization (e.g., multicasts)

notify(value)[source]
class pylablib.core.thread.callsync.QDirectResultSynchronizer(value)[source]

Bases: object

Result “synchronizer” for direct calls.

Behaves as a regular result synchronizer with an already executed call.

get_progress()[source]

Get the progress of the call execution (always return "done")

is_call_done()[source]

Check if the call is done (always return True)

skipped()[source]

Check if the call was skipped (always return False)

failed()[source]

Check if the call failed (always return False)

get_value()[source]

Return stored value

get_value_sync(timeout=None, default=None, error_on_fail=True, error_on_skip=True, pass_exception=True)[source]

Return stored value.

Parameters are only for compatibility with QCallResultSynchronizer.

wait(*args, **kwargs)[source]

Do nothing (present only for compatibility with QCallResultSynchronizer)

notify(*args, **kwargs)[source]

Do nothing (present only for compatibility with QCallResultSynchronizer)

waiting()[source]

Check if waiting is in progress (always return False)

done_wait()[source]

Check if waiting is done (always return True)

success_wait()[source]

Check if waiting is done successfully (always return True)

done_notify()[source]

Check if notifying is done (always return True)

waiting_state()[source]
notifying_state()[source]
class pylablib.core.thread.callsync.QScheduledCall(func, args=None, kwargs=None, silent=False, result_synchronizer=None)[source]

Bases: object

Object representing a scheduled remote call.

Can be executed, skipped, or failed in the target thread, in which case it notifies the result synchronizer (if supplied).

Parameters:
  • func – callable to be invoked in the destination thread

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • silent – if True, silence the exception in the execution thread and simply pass it to the caller thread; otherwise, the exception is raised in both threads

  • result_synchronizer – result synchronizer object; can be None (create new QCallResultSynchronizer), "async" (no result synchronization), or a QCallResultSynchronizer object.

class Callback(func, pass_result, call_on_exception, call_on_unschedule)

Bases: tuple

call_on_exception
call_on_unschedule
func
pass_result
execute(silent=None)[source]

Execute the call and notify the result synchronizer (invoked by the destination thread)

add_callback(callback, pass_result=True, call_on_exception=False, call_on_unschedule=False, front=False)[source]

Set the callback to be executed after the main call is done.

If pass_result==True, pass function result to the callback (or None if call failed); otherwise, pass no arguments. If call_on_exception==True, call it even if the original call raised an exception. If call_on_unschedule==True, call it for any call unscheduling event, including using skip() or fail() methods (this effectively ignores call_on_exception, since the callback is called regardless of the exception). If front==True, add the callback in the front of the line (executes first).

fail()[source]

Notify that the call is failed (invoked by the destination thread)

skip()[source]

Notify that the call is skipped (invoked by the destination thread)

class pylablib.core.thread.callsync.TDefaultCallInfo(call_time)

Bases: tuple

call_time
class pylablib.core.thread.callsync.QScheduler(call_info_argname=None)[source]

Bases: object

Generic call scheduler.

Two methods are used by the external scheduling routines: build_call() to create a QScheduledCall with appropriate parameters, and schedule(), which takes a call and schedules it. The schedule() method should return True if the scheduling was successful (at least, for now), and False otherwise.

Parameters:

call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by build_call_info()) is passed on function call

build_call_info()[source]

Build call info tuple which can be passed to scheduled calls

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)[source]

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

schedule(call)[source]

Schedule the call

clear()[source]

Clear the scheduler

class pylablib.core.thread.callsync.QDirectCallScheduler(call_info_argname=None)[source]

Bases: QScheduler

Simplest call scheduler: directly executes the calls on scheduling in the scheduling thread.

Parameters:

call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=False)[source]

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

schedule(call)[source]

Schedule the call

build_call_info()

Build call info tuple which can be passed to scheduled calls

clear()

Clear the scheduler

class pylablib.core.thread.callsync.QQueueScheduler(on_full_queue='skip_current', call_info_argname=None)[source]

Bases: QScheduler

Call scheduler with a builtin call queue.

Supports placing the calls and retrieving them (from the destination thread). Has ability to skip some calls if, e.g., the queue is too full. Whether the call should be skipped is determined by can_schedule() (should be overloaded in subclasses). Used as a default command scheduler.

Parameters:
  • on_full_queue – action to be taken if the call can’t be scheduled (i.e., can_schedule() returns False); can be "skip_current" (skip the call which is being scheduled), "skip_newest" (skip the most recent call; place the current) "skip_oldest" (skip the oldest call in the queue; place the current), "call_current" (execute the call which is being scheduled immediately in the caller thread), "call_newest" (execute the most recent call immediately in the caller thread), "call_oldest" (execute the oldest call in the queue immediately in the caller thread), or "wait" (wait until the call can be scheduled, which is checked after every call removal from the queue; place the call)

  • call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

Methods to overload:
  • can_schedule(): check if the call can be scheduled

  • call_added(): called when a new call has been added to the queue

  • call_popped(): called when a call has been removed from the queue (either for execution, or for skipping)

can_schedule(call)[source]

Check if the call can be scheduled

call_added(call)[source]

Called whenever call has been added to the queue

call_popped(call, idx)[source]

Called whenever call has been removed from the queue

idx determines the call position within the queue.

schedule(call)[source]

Schedule a call

pop_call()[source]

Pop the call from the queue head.

If the queue is empty, return None

unschedule(call)[source]

Unschedule a given call.

Designed for joint queue operation, so the call is not notified (assume that it has been already notified elsewhere).

has_calls()[source]

Check if there are queued calls

clear(close=True)[source]

Clear the call queue.

If close==True, mark the queue as closed (any attempt to schedule more calls fails automatically) and fail all calls in the queue; otherwise, skip all calls currently in the queue.

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

build_call_info()

Build call info tuple which can be passed to scheduled calls

class pylablib.core.thread.callsync.QQueueLengthLimitScheduler(max_len=1, on_full_queue='skip_current', call_info_argname=None)[source]

Bases: QQueueScheduler

Queued call scheduler with a length limit.

Parameters:
  • max_len – maximal queue length; non-positive values are interpreted as no limit can also be a tuple (arg_name, max_len), in which case the length is calculated separately for every value of the parameter arg_name supplied to the method

  • on_full_queue – action to be taken if the call can’t be scheduled (the queue is full); can be "skip_current" (skip the call which is being scheduled), "skip_newest" (skip the most recent call; place the current) "skip_oldest" (skip the oldest call in the queue; place the current), "call_current" (execute the call which is being scheduled immediately in the caller thread), "call_newest" (execute the most recent call immediately in the caller thread), "call_oldest" (execute the oldest call in the queue immediately in the caller thread), or "wait" (wait until the call can be scheduled, which is checked after every call removal from the queue; place the call)

  • call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

change_max_len(max_len)[source]

Change maximal length of the call queue (doesn’t affect already scheduled calls)

get_current_len()[source]

Get current number of calls in the queue

call_added(call)[source]

Called whenever call has been added to the queue

call_popped(call, idx)[source]

Called whenever call has been removed from the queue

idx determines the call position within the queue.

can_schedule(call)[source]

Check if the call can be scheduled

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

build_call_info()

Build call info tuple which can be passed to scheduled calls

clear(close=True)

Clear the call queue.

If close==True, mark the queue as closed (any attempt to schedule more calls fails automatically) and fail all calls in the queue; otherwise, skip all calls currently in the queue.

has_calls()

Check if there are queued calls

pop_call()

Pop the call from the queue head.

If the queue is empty, return None

schedule(call)

Schedule a call

unschedule(call)

Unschedule a given call.

Designed for joint queue operation, so the call is not notified (assume that it has been already notified elsewhere).

class pylablib.core.thread.callsync.QQueueSizeLimitScheduler(max_size=1, size_calc=None, on_full_queue='skip_current', call_info_argname=None)[source]

Bases: QQueueScheduler

Queued call scheduler with a generic size limit; similar to QQueueLengthLimitScheduler, but more flexible and can implement more restrictions (e.g., queue length and arguments RAM size).

Parameters:
  • max_size – maximal total size of the arguments; can be either a single number, or a tuple (if several different size metrics are involved); non-positive values are interpreted as no limit

  • size_calc – function that takes a single argument (call to be placed) and returns its size; can be either a single number, or a tuple (if several different size metrics are involved); by default, simply returns 1, which makes the scheduler behavior identical to QQueueLengthLimitScheduler

  • on_full_queue – action to be taken if the call can’t be scheduled (the queue is full); can be "skip_current" (skip the call which is being scheduled), "skip_newest" (skip the most recent call; place the current) "skip_oldest" (skip the oldest call in the queue; place the current), "call_current" (execute the call which is being scheduled immediately in the caller thread), "call_newest" (execute the most recent call immediately in the caller thread), "call_oldest" (execute the oldest call in the queue immediately in the caller thread), or "wait" (wait until the call can be scheduled, which is checked after every call removal from the queue; place the call)

  • call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

change_max_size(max_size)[source]

Change size restrictions

get_current_size()[source]

Get current size metrics

call_added(call)[source]

Called whenever call has been added to the queue

call_popped(call, idx)[source]

Called whenever call has been removed from the queue

idx determines the call position within the queue.

can_schedule(call)[source]

Check if the call can be scheduled

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

build_call_info()

Build call info tuple which can be passed to scheduled calls

clear(close=True)

Clear the call queue.

If close==True, mark the queue as closed (any attempt to schedule more calls fails automatically) and fail all calls in the queue; otherwise, skip all calls currently in the queue.

has_calls()

Check if there are queued calls

pop_call()

Pop the call from the queue head.

If the queue is empty, return None

schedule(call)

Schedule a call

unschedule(call)

Unschedule a given call.

Designed for joint queue operation, so the call is not notified (assume that it has been already notified elsewhere).

pylablib.core.thread.callsync.schedule_multiple_queues(call, queues)[source]

Schedule the call simultaneously in several queues.

Go through queues in the given order and schedule call in every one of them. If one of the schedules failed or the call has been executed there, unschedule it from all the previous queues and return False; otherwise, return True.

class pylablib.core.thread.callsync.QMultiQueueScheduler(schedulers, notifiers)[source]

Bases: object

Wrapper around schedule_multiple_queues() which acts as a single scheduler.

Support additional notifiers, which are called if the scheduling is successful (e.g., to notify and wake up the destination thread).

build_call(*args, **kwargs)[source]
schedule(call)[source]
class pylablib.core.thread.callsync.QThreadCallScheduler(thread=None, tag=None, priority=0, interrupt=True, call_info_argname=None)[source]

Bases: QScheduler

Call scheduler via thread calls (QThreadController.call_in_thread_callback())

Parameters:
  • thread – destination thread (by default, thread which creates the scheduler)

  • tag – if supplied, send the call in a message with the given tag; otherwise, use the interrupt call (generally, higher priority method).

  • priority – message priority (only when tag is not None)

  • interrupt – whether the call is an interrupt (call inside any loop, e.g., during waiting or sleeping), or it should be called in the main event loop

  • call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

schedule(call)[source]

Schedule the call

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

build_call_info()

Build call info tuple which can be passed to scheduled calls

clear()

Clear the scheduler

class pylablib.core.thread.callsync.QMulticastThreadCallScheduler(thread=None, limit_queue=1, tag=None, priority=0, interrupt=True, call_info_argname=None)[source]

Bases: QThreadCallScheduler

Extended call scheduler via thread calls, which can limit number of queued calls.

Parameters:
  • thread – destination thread (by default, thread which creates the scheduler)

  • limit_queue – call queue limit (non-positive numbers are interpreted as no limit)

  • tag – if supplied, send the call in a message with the given tag; otherwise, use the interrupt call (generally, higher priority method).

  • priority – message priority (only when tag is not None)

  • interrupt – whether the call is an interrupt (call inside any loop, e.g., during waiting or sleeping), or it should be called in the main event loop

  • call_info_argname – if not None, supplies a name of a keyword argument via which call info (generated by QScheduler.build_call_info()) is passed on function call

schedule(call)[source]

Schedule the call

build_call(func, args=None, kwargs=None, callback=None, pass_result=True, callback_on_exception=True, sync_result=True)

Build QScheduledCall for subsequent scheduling.

Parameters:
  • func – function to be called

  • args – arguments to be passed to func

  • kwargs – keyword arguments to be passed to func

  • callback – optional callback to be called when func is done

  • pass_result (bool) – if True, pass func result as a single argument to the callback; otherwise, give no arguments

  • callback_on_exception (bool) – if True, execute the callback on call fail or skip (if it requires an argument, None is supplied); otherwise, only execute it if the call was successful

  • sync_result – if True, the call has a default result synchronizer; otherwise, no synchronization is made.

build_call_info()

Build call info tuple which can be passed to scheduled calls

clear()

Clear the scheduler

pylablib.core.thread.controller module

pylablib.core.thread.controller.exint(error_msg_template='{}:', pass_stop_exception=False)[source]

Context that intercepts exceptions and stops the execution in a controlled manner (quitting the main thread)

pylablib.core.thread.controller.add_exception_hook(name, func, single_call=False)[source]

Add an exception hook, which is called whenever exception is caught via exint() wrapper.

If single_call==True, the hook is removed from the set when it is called.

pylablib.core.thread.controller.remove_exception_hook(name)[source]

Remove the exception hook with the given name

pylablib.core.thread.controller.exsafe(func)[source]

Decorator that intercepts exceptions raised by func and stops the execution in a controlled manner (quitting the main thread)

pylablib.core.thread.controller.exsafeSlot(*slargs, **slkwargs)[source]

Wrapper around Qt slot which intercepts exceptions and stops the execution in a controlled manner

pylablib.core.thread.controller.toploopSlot(*slargs, **slkwargs)[source]

Wrapper around Qt slot which intercepts exceptions and stops the execution in a controlled manner

class pylablib.core.thread.controller.QThreadControllerThread(controller)[source]

Bases: object

finalized = <Mock name='mock.QtCore.pyqtSignal()' id='139946557760272'>
run()[source]
quit_sync()[source]
pylablib.core.thread.controller.remote_call(func)[source]

Decorator that turns a controller method into a remote call (call from a different thread is passed synchronously)

pylablib.core.thread.controller.call_in_thread(thread_name, interrupt=True, pass_exception=True, silent=False, sync=True)[source]

Decorator that turns any function into a remote call in a thread with a given name (call from a different thread is passed synchronously)

pylablib.core.thread.controller.call_in_gui_thread(func=None, interrupt=True, pass_exception=True, silent=False, sync=True)[source]

Decorator that turns any function into a remote call in a GUI thread (call from a different thread is passed synchronously)

pylablib.core.thread.controller.gui_thread_method(func)[source]

Decorator for an object’s method that checks if the object’s gui_thread_safe attribute is true, in which case the call is routed to the GUI thread

class pylablib.core.thread.controller.QThreadController(name=None, kind='loop', multicast_pool=None)[source]

Bases: object

Generic Qt thread controller.

Responsible for all inter-thread synchronization. There is one controller per thread, and

Parameters:
  • name (str) – thread name (by default, generate a new unique name); this name can be used to obtain thread controller via get_controller()

  • kind (str) – thread kind; can be "loop" (thread is running in the Qt message loop; behavior is implemented in process_message() and remote calls), "run" (thread executes run() method and quits after it is complete), or "main" (can only be created in the main GUI thread)

  • multicast_poolMulticastPool for this thread (by default, use the default common pool)

Methods to overload:
  • on_start(): executed on the thread startup (between synchronization points "start" and "run")

  • on_finish(): executed on thread cleanup (attempts to execute in any case, including exceptions)

  • run(): executed once per thread; thread is stopped afterwards (only if kind=="run")

  • process_message(): function that takes 2 arguments (tag and value) of the message and processes it; returns True if the message has been processed and False otherwise

    (in which case it is stored and can be recovered via wait_for_message()/pop_message()); by default, always return False

  • process_interrupt(): function that tales 2 arguments (tag and value) of the interrupt message (message with a tag starting with "interrupt.") and processes it;

    by default, assumes that any value with tag "execute" is a function and executes it

Signals:
  • started: emitted on thread start (after on_start() is executed)

  • finished: emitted on thread finish (before on_finish() is executed)

started = <Mock name='mock.QtCore.pyqtSignal()' id='139946557760272'>

This signal is emitted after the thread has started (after the setup code has been executed, before its lifetime state is changed)

finished = <Mock name='mock.QtCore.pyqtSignal()' id='139946557760272'>

This signal is emitted before the thread has finished (before the cleanup code has been executed, after its lifetime state is changed)

allowing_toploop(depth=1)[source]

Context manager which temporarily treats the current loop level and several deeper levels as a top loop.

All event loops which lie up to depth below this one are treated as top loops.

blocking_control_signals(kinds='all', ignore=None)[source]

Context manager which temporarily blocks external control signals.

After leaving the wrapped code segment, all of the blocked but not ignored calls are executed. kind determines the kind of calls to block; it is a collection of elements among "message", "stop", and "call" and blocks, correspondingly, messages, stop signals, and any call_in_thread-related requests; can be also be "all", which includes all of these categories. ignore specifies kinds which are completely ignored if sent during the blocking interval; can also be "all", which includes all of the kinds categories. Useful to temporarily “suspend” the thread communication with other threads, especially for the main GUI thread (e.g., to show a blocking message box). Local call method.

wait_for_message(tag, timeout=None, top_loop=False)[source]

Wait for a single message with a given tag.

Return value of a received message with this tag. If timeout is passed, raise threadprop.TimeoutThreadError. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

new_messages_number(tag)[source]

Get the number of queued messages with a given tag.

Local call method.

pop_message(tag)[source]

Pop the latest message with the given tag.

Select the message with the highest priority, and among those the oldest one. If no messages are available, raise threadprop.NoMessageThreadError. Local call method.

wait_for_sync(tag, uid, timeout=None)[source]

Wait for synchronization signal with the given tag and UID.

This method is rarely invoked directly, and is usually used by synchronizers code. If timeout is passed, raise threadprop.TimeoutThreadError. Local call method.

wait_for_any_message(timeout=None, top_loop=False)[source]

Wait for any message (including synchronization messages or pokes).

If timeout is passed, raise threadprop.TimeoutThreadError. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

wait_until(check, timeout=None, top_loop=False)[source]

Wait until a given condition is true.

Condition is given by the check function, which is called after every new received message and should return True if the condition is met. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). If timeout is passed, raise threadprop.TimeoutThreadError. Local call method.

check_messages(top_loop=False)[source]

Receive new messages.

Runs the underlying message loop to process newly received message and signals (and place them in corresponding queues if necessary). This method is rarely invoked, and only should be used periodically during long computations to not ‘freeze’ the thread. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

sleep(timeout, wake_on_message=False, top_loop=False)[source]

Sleep for a given time (in seconds).

Unlike time.sleep(), constantly checks the event loop for new messages (e.g., if stop or interrupt commands are issued). In addition, if wake_on_message==True, wake up if any message has been received; it this case. return True if the wait has been completed, and False if it has been interrupted by a message. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). If timeout is None, wait forever (usually, until the application is closed, or some interrupt message raises and error). Local call method.

no_stopping()[source]

Context manager, which temporarily suspends stop requests (InterruptExceptionStop exceptions).

If the stop request has been made within this block, raise the exception on exit. Note that stop() method and, correspondingly, stop_controller() still work, when called from the controlled thread.

process_interrupt(tag, value)[source]

Process a new interrupt.

If the function returns False, the interrupt is put in the corresponding queue. Otherwise, the the message is interrupt to be already, and it gets ‘absorbed’. Local call method, called automatically.

process_message(tag, value)[source]

Process a new message.

If the function returns False, the message is put in the corresponding queue. Otherwise, the the message is considered to be already, and it gets ‘absorbed’. Local call method, called automatically.

on_start()[source]

Method invoked on the start of the thread.

Local call method, called automatically.

on_finish()[source]

Method invoked in the end of the thread.

Called regardless of the stopping reason (normal finishing, exception, application finishing). Local call method, called automatically.

run()[source]

Method called to run the main thread code (only for "run" thread kind).

Local call method, called automatically.

subscribe_sync(callback, srcs='any', tags=None, dsts='any', filt=None, subscription_priority=0, limit_queue=None, call_interrupt=True, add_call_info=False, return_result=False, sid=None)[source]

Subscribe a synchronous callback to a multicast.

If a multicast is sent, callback is called from the dest_controller thread (by default, thread which is calling this function) via the thread call mechanism (QThreadController.call_in_thread_callback()). In Qt, analogous to making a signal connection with a queued call. By default, the subscribed destination is the thread’s name. Local call method.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • subscription_priority (int) – subscription priority (higher priority subscribers are called first).

  • limit_queue (int) – limits the maximal number of scheduled calls (if the multicast is sent while at least limit_queue callbacks are already in queue to be executed, ignore it) 0 or negative value means no limit (not recommended, as it can increase the queue indefinitely if the multicast rate is high enough)

  • call_interrupt – whether the call is an interrupt (call inside any loop, e.g., during waiting or sleeping), or it should be called in the main event loop

  • add_call_info (bool) – if True, add a fourth argument containing a call information (tuple with a single element, a timestamps of the call).

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique name).

subscribe_direct(callback, srcs='any', tags=None, dsts='any', filt=None, subscription_priority=0, scheduler=None, return_result=False, sid=None)[source]

Subscribe asynchronous callback to a multicast.

If a multicast is sent, callback is called from the sending thread (not subscribed thread). Therefore, should be used with care. In Qt, analogous to making a signal connection with a direct call. By default, the subscribed destination is the thread’s name. Local call method.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • subscription_priority (int) – subscription priority (higher priority subscribers are called first).

  • scheduler – if defined, multicast call gets scheduled using this scheduler instead of being called directly (which is the default behavior)

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique id and return it).

unsubscribe(sid)[source]

Unsubscribe from a subscription with a given ID.

Note that multicasts which are already emitted but not processed will remain in the queue; if they need to be ignored, it should be handled explicitly. Local call method.

send_multicast(dst='any', tag=None, value=None, src=None, filter_results=True)[source]

Send a multicast to the multicast pool.

By default, the multicast source is the thread’s name. Return result synchronizers for all executed subscribed methods. Local call method.

Parameters:
  • dst (str) – multicast destination; can be a name, "all" (will pass all subscribers’ destination filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" destination).

  • tag (str) – multicast tag.

  • value – multicast value.

  • src (str) – multicast source; can be None (current thread name), a specific name, "all" (will pass all subscribers’ source filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" source).

  • filter_results – if True, filter the results to exclude dummy synchronizers, which correspond to calls which do not return anything

send_multicast_sync(dst='any', tag=None, value=None, src=None, timeout=None, default_result=None, pass_exception=True)[source]

Send a multicast to the multicast pool and synchronize the results, if available.

By default, the multicast source is the thread’s name. Results are collected and synchronized only from the subscriptions which return them (i.e., set return_result=True). Local call method.

Parameters:
  • dst (str) – multicast destination; can be a name, "all" (will pass all subscribers’ destination filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" destination).

  • tag (str) – multicast tag.

  • value – multicast value.

  • src (str) – multicast source; can be None (current thread name), a specific name, "all" (will pass all subscribers’ source filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" source).

  • timeout – synchronization timeout (None means waiting forever)

  • default_result – default result value if synchronization failed (timed out, thread stopped, etc.)

  • pass_exception – if True and the signal processor raised an exception, raise it in this thread as well If pass_exception==True and the returned value represents exception, re-raise it in the caller thread; otherwise, return default.

set_variable(name, value, update=False, notify=False, notify_tag='changed/*', simple=False)[source]

Set thread variable.

Can be called in any thread (controlled or external). If notify==True, send an multicast with the given notify_tag (where "*" symbol is replaced by the variable name). If update==True and the value is a dictionary, update the branch rather than overwrite it. If simple==True, assume that the result is a single atomic variable, in which case the lock is not used; note that in this case the threads waiting on this variable (or branches containing it) will not be notified. Local call method.

delete_variable(name, missing_error=False)[source]

Delete thread variable.

If missing_error==False and no variable exists, do nothing; otherwise, raise and error. Local call method.

set_func_variable(name, func, use_lock=True)[source]

Set a ‘function’ variable.

Acts as a thread variable to the external user, but instead of reading a stored value, it executed a function instead. Note, that the function is executed in the caller thread (i.e., the thread which tries to access the variable), so use of synchronization methods (commands, signals, locks) is highly advised.

If use_lock==True, then the function call will be wrapped into the usual variable lock, i.e., it won’t run concurrently with other variable access. Local call method.

add_thread_method(name, method, interrupt=True)[source]

Add a thread method.

Adds a named method to the thread, which can be called later using call_thread_method(). This method will be called in this thread.

Useful for GUI thread to set up some global access methods, which other threads can safely use. For QTaskThread threads it’s a better idea to set up a command instead. Local call method.

delete_thread_method(name)[source]

Delete a thread method.

Local call method.

call_thread_method(name, *args, **kwargs)[source]

Call a thread method.

Method needs to be set up beforehand using add_thread_method(). It is always executed in the current thread. Local call method.

send_message(tag, value, priority=0)[source]

Send a message to the thread with a given tag, value and priority.

External call method.

send_interrupt(tag, value, priority=0)[source]

Send an interrupt message to the thread with a given tag, value and priority.

External call method.

send_sync(tag, uid)[source]

Send a synchronization signal with the given tag and UID.

This method is rarely invoked directly, and is usually used by synchronizers code (e.g., QThreadNotifier). External call method.

get_variable(name, default=None, copy_branch=True, missing_error=False, simple=False)[source]

Get thread variable.

If missing_error==False and no variable exists, return default; otherwise, raise and error. If copy_branch==True and the variable is a Dictionary branch, return its copy to ensure that it stays unaffected on possible further variable assignments. If simple==True, assume that the result is a single atomic variable, in which case the lock is not used; this only works with actual variables and not function variables. Universal call method.

sync_variable(name, pred, timeout=None)[source]

Wait until thread variable with the given name satisfies the condition given by pred.

pred can be a variable values, a container (list, set, tuple) of possible values, or a function which takes one argument (variable value) and returns whether the condition is satisfied. It is executed in the caller thread. External call method.

start()[source]

Start the thread.

External call method.

request_stop()[source]

Request thread stop (send a stop command).

External call method.

stop(code=0, sync=False)[source]

Stop the thread.

If called from the thread, stop immediately by raising a threadprop.InterruptExceptionStop exception. Otherwise, schedule thread stop. If the thread kind is "main", stop the whole application with the given exit code. Otherwise, stop the thread. If sync==True and the thread is not main or current, wait until it is completely stopped. Universal call method.

sync_stop()[source]

Wait until the controller and the thread are stopped.

External call method.

poke()[source]

Send a dummy message to the thread.

A cheap way to notify the thread that something happened (useful for, e.g., making thread leave wait_for_any_message() method). External call method.

running()[source]

Check if the thread is running

finishing()[source]

Check if the thread is finishing

notify_exec_point(point)[source]

Mark the given execution point as passed.

Automatically invoked points include "start" (thread starting), "run" (thread setup and ready to run), "cleanup" (thread stopping is invoked, starting to clean up) and "stop" (thread finished). Can be extended for arbitrary points. Local call method.

fail_exec_point(point)[source]

Mark the given execution point as failed.

Automatically invoked for "run" (thread setup and ready to run) if the startup raised an error before the thread properly started ("start", "cleanup", and "stop" are notified in any case) Can be extended for arbitrary points. Local call method.

get_exec_counter(point)[source]

Get the counter (number of notifications) for the given point.

See sync_exec_point() for details. External call.

sync_exec_point(point, timeout=None, counter=1)[source]

Wait for the given execution point.

Automatically invoked points include "start" (thread starting), "run" (thread setup and ready to run), "cleanup" (thread stopping is invoked, starting to clean up) and "stop" (thread finished). If timeout is passed, raise threadprop.TimeoutThreadError. counter specifies the minimal number of pre-requisite notify_exec_point() calls to finish the waiting (by default, a single call is enough). Return actual number of notifier calls up to date. External call method.

add_stop_notifier(func, call_if_stopped=True)[source]

Add stop notifier: a function which is called when the thread is about to be stopped (left the main message loop).

The supplied function is called in the controlled thread close to its shutdown, so it should be short, non-blocking, and thread-safe. If the thread is already stopped and call_if_stopped==True, call func immediately (from the caller’s thread). Return True if the thread is still running and the notifier is added, and False otherwise. Local call method.

remove_stop_notifier(func)[source]

Remove the stop notifier from this controller.

Return True if the notifier was in this thread and is now removed, and False otherwise. Local call method.

is_in_controlled()[source]

Check if the thread executing this code is controlled by this controller

call_in_thread_callback(func, args=None, kwargs=None, callback=None, tag=None, priority=0, interrupt=True)[source]

Call a function in this thread with the given arguments.

If callback is supplied, call it with the result as a single argument (call happens in the controller thread). If tag is supplied, send the call in a message with the given tag; otherwise, use the interrupt call (generally, higher priority method). If interrupt==True, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. Universal call method.

call_in_thread_sync(func, args=None, kwargs=None, sync=True, callback=None, timeout=None, default_result=None, pass_exception=True, silent=False, tag=None, priority=0, interrupt=True, error_on_stopped=True, same_thread_shortcut=True)[source]

Call a function in this thread with the given arguments.

If sync==True, calling thread is blocked until the controlled thread executes the function, and the function result is returned (in essence, the fact that the function executes in a different thread is transparent). Otherwise, exit call immediately, and return a synchronizer object (QCallResultSynchronizer), which can be used to check if the call is done (method is_done) and obtain the result (method QCallResultSynchronizer.get_value_sync()). If callback is not None, call it after the function is successfully executed (from the target thread), with a single parameter being function result. If pass_exception==True and func raises an exception, re-raise it in the caller thread (applies only if sync==True). If silent==True and func raises an exception, silence it in the execution thread and only re-raise it in the caller thread; note that if pass_exception==False and silent==True, the exception is ignored in both threads. If tag is supplied, send the call in a message with the given tag and priority; otherwise, use the interrupt call (generally, higher priority method). If interrupt==True, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. If error_on_stopped==True and the controlled thread is stopped before it executed the call, raise threadprop.NoControllerThreadError; otherwise, return default_result. If same_thread_shortcut==True (default), the call is synchronous, and the caller thread is the same as the controlled thread, call the function directly. Universal call method.

class pylablib.core.thread.controller.QTaskThread(name=None, args=None, kwargs=None, multicast_pool=None)[source]

Bases: QThreadController

Thread which allows to set up and run jobs and batch jobs with a certain time period, and execute commands in the meantime.

Parameters:
  • name (str) – thread name (by default, generate a new unique name)

  • args – args supplied to setup_task() method

  • kwargs – keyword args supplied to setup_task() method

  • multicast_poolMulticastPool for this thread (by default, use the default common pool)

ca

asynchronous command accessor, which makes calls more function-like; ctl.ca.comm(*args,**kwarg) is equivalent to ctl.call_command("comm",args,kwargs,sync=False)

cai

asynchronous command accessor which ignores and silences any exceptions (including missing /stopped controller) useful for sending queries during thread finalizing / application shutdown, when it’s not guaranteed that the command recipient is running ctl.cai.comm(*args,**kwarg) is equivalent to ctl.call_command("comm",args,kwargs,sync=False,ignore_errors=True)

cad

asynchronous command accessor returning a result synchronizer, which makes calls more function-like; ctl.cad.comm(*args,**kwarg) is equivalent to ctl.call_command("comm",args,kwargs,sync="delayed")

cs

synchronous command accessor, which makes calls more function-like; ctl.cs.comm(*args,**kwarg) is equivalent to ctl.call_command("comm",args,kwargs,sync=True)

css

synchronous command accessor which is made ‘exception-safe’ via exsafe() wrapper (i.e., safe to directly connect to slots) ctl.css.comm(*args,**kwarg) is equivalent to with exint(): ctl.call_command("comm",args,kwargs,sync=True)

csi

synchronous command accessor which ignores and silences any exceptions (including missing /stopped controller) useful for sending queries during thread finalizing / application shutdown, when it’s not guaranteed that the command recipient is running

m

method accessor; directly calls the method corresponding to the command; ctl.m.comm(*args,**kwarg) is equivalent to ctl.call_command("comm",*args,**kwargs), which is often also equivalent to ctl.comm(*args,**kwargs); for most practical purposes it’s the same as directly invoking the class method, but it makes intent more explicit (as command methods are usually not called directly from other threads), and it doesn’t invoke warning about calling method instead of command from another thread.

Methods to overload:
  • setup_task(): executed on the thread startup (between synchronization points "start" and "run")

  • finalize_task(): executed on thread cleanup (attempts to execute in any case, including exceptions)

class TBatchJob(job, cleanup, min_run_time, priority)

Bases: tuple

cleanup
job
min_run_time
priority
class TCommand(command, scheduler, priority)

Bases: tuple

command
priority
scheduler
class Job(job, period, queue, jobs_order)[source]

Bases: object

A single job loop.

Deals with scheduling, time counting, pausing, and cleanup.

Parameters:
  • job – job function

  • period – job period

  • queue – thread controller’s scheduling queue, to which the job must be added

  • jobs_order – thread controller’s job queue which determines the jobs scheduling order

schedule()[source]

Schedule the job

mark_unscheduled()[source]

Mark the job as unscheduled.

Called automatically on job completion.

unschedule()[source]

Manually unschedule the job (e.g., when paused or removed)

clear()[source]

Clear the job and remove it from the jobs list

change_period(period)[source]

Change the job period

pause(paused=True, unschedule=True)[source]

Pause or resume the job.

If pausing and unschedule==True, remove already scheduled job from the queue.

time_left(t=None)[source]

Get the amount of time left till the next call, or None if the job is paused

add_job(name, job, period, initial_call=True, priority=-10)[source]

Add a recurrent job which is called every period seconds.

The job starts running automatically when the main thread loop start executing. If initial_call==True, call job once immediately after adding. priority specifies the call priority in the scheduling queue; by default, it is lower than the command and multicasts (0). Local call method.

change_job_period(name, period)[source]

Change the period of the job name.

Local call method.

remove_job(name)[source]

Remove the job name from the job list.

Local call method.

add_batch_job(name, job, cleanup=None, min_runtime=0, priority=-10)[source]

Add a batch job which is executed once, but with continuations.

After this call the job is just created, but is not running. To start it, call start_batch_job(). If specified, cleanup is a finalizing function which is called both when the job terminates normally, and when it is forcibly stopped (including thread termination). min_runtime specifies minimal expected runtime of a job; if a job executes faster than this time, it is repeated again unless at least min_runtime seconds passed; useful for high-throughput jobs, as it reduces overhead from the job scheduling mechanism (repeating within min_runtime time window is fast)

Unlike the usual recurrent jobs, here job is a generator (usually defined by a function with yield statement). When the job is running, the generator is periodically called until it raises StopIteration exception, which signifies that the job is finished. From generator function point of view, after the job is started, the function is executed normally, but every time yield statement is encountered, the execution is suspended for period seconds (specified in start_batch_job()). priority specifies the call priority in the scheduling queue; by default, it is lower than the command and multicasts (0). Local call method.

change_batch_job_parameters(name, job='keep', cleanup='keep', min_runtime='keep', priority='keep', stop=False, restart=False)[source]

Change parameters (main body, cleanup function, and minimal runtime) of the batch job.

The parameters are the same as for add_batch_job(). If any of them are "keep", don’t change them. If stop==True, stop the job before changing the parameters; otherwise the job is continued with the previous parameters (including cleanup) until it is stopped and restarted. If restart==True, restart the job after changing the parameters. Local call method.

remove_batch_job(name)[source]

Remove the batch job name, stopping it if necessary.

Local call method.

start_batch_job(name, period, *args, start_immediate=True, **kwargs)[source]

Start the batch job with the given name.

period specifies suspension period. Optional arguments are passed to the job and the cleanup functions. If start_immediate==True, start the job (i.e., run the first iteration) immediately during the call; otherwise, start it only when it is scheduled, after the currently running call is complete. Local call method.

is_batch_job_running(name)[source]

Check if a given batch job running.

Local call method.

stop_batch_job(name, stop_immediate=True, error_on_stopped=False)[source]

Stop a given batch job.

If error_on_stopped==True and the job is not currently running, raise an error. Otherwise, do nothing. If stop_immediate==True, stop the job (i.e., unschedule it and run the cleanup code) immediately during the call; otherwise, stop it when its next iteration is called. Local call method.

restart_batch_job(name, start_immediate=True, error_on_stopped=False)[source]

Restart the running batch job with its current arguments.

If error_on_stopped==True and the job is not currently running, raise an error. Otherwise, do nothing. Local call method.

run_as_batch_job(job, period, cleanup=None, name=None, priority=-10, start_immediate=True, args=None, kwargs=None)[source]

Create a temporarily batch job and immediately run it.

If name is None, generate a new unique name. The job is removed after it is complete (i.e., after cleanup). Note that this implies, that it can not be restarted using restart_batch_job(), as it will be removed after the stopping before the restart. All the parameters are the same as for add_batch_job() and start_batch_job(). Return the batch job name (either supplied or newly generated).

run()[source]

Method called to run the main thread code (only for "run" thread kind).

Local call method, called automatically.

on_start()[source]

Method invoked on the start of the thread.

Local call method, called automatically.

on_finish()[source]

Method invoked in the end of the thread.

Called regardless of the stopping reason (normal finishing, exception, application finishing). Local call method, called automatically.

setup_task(*args, **kwargs)[source]

Setup the thread (called before the main task loop).

Local call method, called automatically.

finalize_task()[source]

Finalize the thread (always called on thread termination, regardless of the reason).

Local call method, called automatically.

update_status(kind, status, text=None, notify=True)[source]

Update status represented in thread variables.

kind is the status kind and status is its value. Status variable name is "status/"+kind. If text is not None, it specifies new status text stored in "status/"+kind+"_text". If notify==True, send an multicast about the status change. Local call method.

add_command(name, command=None, scheduler=None, limit_queue=None, on_full_queue='skip_current', priority=0)[source]

Add a new command to the command set.

Return scheduler, which can be used for adding another command (if the same queue should be used for several commands). Local call method.

Parameters:
  • name – command name

  • command – command function; if None, look for the method with the given name.

  • scheduler – a command scheduler; by default, it is a QQueueLengthLimitScheduler, which maintains a call queue with the given length limit and full queue behavior; can also be a name of a different command, with which it will share a single queue with the same limitations; if supplied, limit_queue and on_full_queue parameters are ignored

  • limit_queue – command call queue limit; None means no limit

  • on_full_queue – action to be taken if the call can’t be scheduled (the queue is full); can be "skip_current" (skip the call which is being scheduled), "skip_newest" (skip the most recent call; place the current) "skip_oldest" (skip the oldest call in the queue; place the current), "call_current" (execute the call which is being scheduled immediately in the caller thread), "call_newest" (execute the most recent call immediately in the caller thread), "call_oldest" (execute the oldest call in the queue immediately in the caller thread), or "wait" (wait until the call can be scheduled, which is checked after every call removal from the queue; place the call)

  • priority – command priority; higher-priority multicasts and commands are always executed before the lower-priority ones.

add_direct_call_command(name, command=None, error_on_async=True)[source]

Add a direct method call which appears as a command.

Unlike regular commands, the call is executed directly in the caller thread (i.e., it is identical to the direct method call). Useful for lightweight and/or lock-wrapped methods, which can be called in a thread-safe way, but which still use command interface for consistency. Note that this kind of commands doesn’t have the same level of synchronization as regular commands (e.g., it can be executed during execution of another command, or commsync multicast method). Local call method.

Parameters:
  • name – command name

  • command – command function; if None, look for the method with the given name.

  • error_on_async – if True and the command is called asynchronously, raise an error; otherwise, substitute for a synchronous call

subscribe_commsync(callback, srcs='any', tags=None, dsts='any', filt=None, subscription_priority=0, scheduler=None, limit_queue=None, on_full_queue='skip_current', priority=0, add_call_info=False, return_result=False, sid=None)[source]

Subscribe a callback to a multicast which is synchronized with commands and jobs execution.

Unlike the standard QThreadController.subscribe_sync() method, the subscribed callback will only be executed between jobs or commands, not during one of these. Local call method.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • subscription_priority (int) – subscription priority (higher priority subscribers are called first).

  • scheduler – if defined, multicast call gets scheduled using this scheduler; by default, create a new call queue scheduler with the given limit_queue, on_full_queue and add_call_info arguments.

  • limit_queue (int) – limits the maximal number of scheduled calls (if the multicast is sent while at least limit_queue callbacks are already in queue to be executed, ignore it) 0 or negative value means no limit (not recommended, as it can increase the queue indefinitely if the multicast rate is high enough)

  • on_full_queue – action to be taken if the call can’t be scheduled (the queue is full); can be "skip_current" (skip the call which is being scheduled), "skip_newest" (skip the most recent call; place the current) "skip_oldest" (skip the oldest call in the queue; place the current), "call_current" (execute the call which is being scheduled immediately in the caller thread), "call_newest" (execute the most recent call immediately in the caller thread), "call_oldest" (execute the oldest call in the queue immediately in the caller thread), or "wait" (wait until the call can be scheduled, which is checked after every call removal from the queue; place the call)

  • add_call_info (bool) – if True, add a fourth argument containing a call information (tuple with a single element, a timestamps of the call).

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique id and return it).

call_command_direct(name, args=None, kwargs=None)[source]

Invoke a command directly and immediately in the current thread.

Universal call method.

call_command(name, args=None, kwargs=None, sync=False, callback=None, timeout=None, ignore_errors=False)[source]

Invoke command call with the given name and arguments

If callback is not None, call it after the command is successfully executed (from the target thread), with a single parameter being the command result. If sync==True, pause caller thread execution (for at most timeout seconds) until the command has been executed by the target thread, and then return the command result. If sync=="delayed", return QCallResultSynchronizer object which can be used to wait for and read the command result; otherwise, return None. In the sync==True case, if ignore_errors==True, ignore all possible problems with the call (controller stopped, call raised an exception, call was skipped) and return None instead; otherwise, these problems raise exceptions in the caller thread. Universal call method.

call_in_thread_commsync(func, args=None, kwargs=None, sync=True, timeout=None, priority=0, ignore_errors=False, same_thread_shortcut=True)[source]

Call a function in this thread such that it is synchronous with other commands, and jobs.

Mostly equivalent to calling a command, only the command function is supplied instead of its name, and the advanced scheduling (maximal schedule size, sharing with different commands, etc.) is not used. args and kwargs specify the function arguments. If sync==True, pause caller thread execution (for at most timeout seconds) until the command has been executed by the target thread, and then return the command result. If sync=="delayed", return QCallResultSynchronizer object which can be used to wait for and read the command result; otherwise, return None. priority sets the call priority (by default, the same as the standard commands). In the sync==True case, if ignore_errors==True, ignore all possible problems with the call (controller stopped, call raised an exception, call was skipped) and return None instead; otherwise, these problems raise exceptions in the caller thread. If same_thread_shortcut==True (default) and the caller thread is the same as the controlled thread, call the function directly. Universal call method.

comm_paused()[source]

Context manager, which allows to temporarily pause all calls (commands, jobs, etc.)

class CommandAccess(parent, sync, direct=False, timeout=None, safe=False, ignore_errors=False)[source]

Bases: object

Accessor object designed to simplify command syntax.

Automatically created by the thread, so doesn’t need to be invoked externally.

add_stop_notifier(func, call_if_stopped=True)

Add stop notifier: a function which is called when the thread is about to be stopped (left the main message loop).

The supplied function is called in the controlled thread close to its shutdown, so it should be short, non-blocking, and thread-safe. If the thread is already stopped and call_if_stopped==True, call func immediately (from the caller’s thread). Return True if the thread is still running and the notifier is added, and False otherwise. Local call method.

add_thread_method(name, method, interrupt=True)

Add a thread method.

Adds a named method to the thread, which can be called later using call_thread_method(). This method will be called in this thread.

Useful for GUI thread to set up some global access methods, which other threads can safely use. For QTaskThread threads it’s a better idea to set up a command instead. Local call method.

allowing_toploop(depth=1)

Context manager which temporarily treats the current loop level and several deeper levels as a top loop.

All event loops which lie up to depth below this one are treated as top loops.

blocking_control_signals(kinds='all', ignore=None)

Context manager which temporarily blocks external control signals.

After leaving the wrapped code segment, all of the blocked but not ignored calls are executed. kind determines the kind of calls to block; it is a collection of elements among "message", "stop", and "call" and blocks, correspondingly, messages, stop signals, and any call_in_thread-related requests; can be also be "all", which includes all of these categories. ignore specifies kinds which are completely ignored if sent during the blocking interval; can also be "all", which includes all of the kinds categories. Useful to temporarily “suspend” the thread communication with other threads, especially for the main GUI thread (e.g., to show a blocking message box). Local call method.

call_in_thread_callback(func, args=None, kwargs=None, callback=None, tag=None, priority=0, interrupt=True)

Call a function in this thread with the given arguments.

If callback is supplied, call it with the result as a single argument (call happens in the controller thread). If tag is supplied, send the call in a message with the given tag; otherwise, use the interrupt call (generally, higher priority method). If interrupt==True, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. Universal call method.

call_in_thread_sync(func, args=None, kwargs=None, sync=True, callback=None, timeout=None, default_result=None, pass_exception=True, silent=False, tag=None, priority=0, interrupt=True, error_on_stopped=True, same_thread_shortcut=True)

Call a function in this thread with the given arguments.

If sync==True, calling thread is blocked until the controlled thread executes the function, and the function result is returned (in essence, the fact that the function executes in a different thread is transparent). Otherwise, exit call immediately, and return a synchronizer object (QCallResultSynchronizer), which can be used to check if the call is done (method is_done) and obtain the result (method QCallResultSynchronizer.get_value_sync()). If callback is not None, call it after the function is successfully executed (from the target thread), with a single parameter being function result. If pass_exception==True and func raises an exception, re-raise it in the caller thread (applies only if sync==True). If silent==True and func raises an exception, silence it in the execution thread and only re-raise it in the caller thread; note that if pass_exception==False and silent==True, the exception is ignored in both threads. If tag is supplied, send the call in a message with the given tag and priority; otherwise, use the interrupt call (generally, higher priority method). If interrupt==True, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. If error_on_stopped==True and the controlled thread is stopped before it executed the call, raise threadprop.NoControllerThreadError; otherwise, return default_result. If same_thread_shortcut==True (default), the call is synchronous, and the caller thread is the same as the controlled thread, call the function directly. Universal call method.

call_thread_method(name, *args, **kwargs)

Call a thread method.

Method needs to be set up beforehand using add_thread_method(). It is always executed in the current thread. Local call method.

check_messages(top_loop=False)

Receive new messages.

Runs the underlying message loop to process newly received message and signals (and place them in corresponding queues if necessary). This method is rarely invoked, and only should be used periodically during long computations to not ‘freeze’ the thread. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

delete_thread_method(name)

Delete a thread method.

Local call method.

delete_variable(name, missing_error=False)

Delete thread variable.

If missing_error==False and no variable exists, do nothing; otherwise, raise and error. Local call method.

fail_exec_point(point)

Mark the given execution point as failed.

Automatically invoked for "run" (thread setup and ready to run) if the startup raised an error before the thread properly started ("start", "cleanup", and "stop" are notified in any case) Can be extended for arbitrary points. Local call method.

finished = <Mock name='mock.QtCore.pyqtSignal()' id='139946557760272'>

This signal is emitted before the thread has finished (before the cleanup code has been executed, after its lifetime state is changed)

finishing()

Check if the thread is finishing

get_exec_counter(point)

Get the counter (number of notifications) for the given point.

See sync_exec_point() for details. External call.

get_variable(name, default=None, copy_branch=True, missing_error=False, simple=False)

Get thread variable.

If missing_error==False and no variable exists, return default; otherwise, raise and error. If copy_branch==True and the variable is a Dictionary branch, return its copy to ensure that it stays unaffected on possible further variable assignments. If simple==True, assume that the result is a single atomic variable, in which case the lock is not used; this only works with actual variables and not function variables. Universal call method.

is_in_controlled()

Check if the thread executing this code is controlled by this controller

new_messages_number(tag)

Get the number of queued messages with a given tag.

Local call method.

no_stopping()

Context manager, which temporarily suspends stop requests (InterruptExceptionStop exceptions).

If the stop request has been made within this block, raise the exception on exit. Note that stop() method and, correspondingly, stop_controller() still work, when called from the controlled thread.

notify_exec_point(point)

Mark the given execution point as passed.

Automatically invoked points include "start" (thread starting), "run" (thread setup and ready to run), "cleanup" (thread stopping is invoked, starting to clean up) and "stop" (thread finished). Can be extended for arbitrary points. Local call method.

poke()

Send a dummy message to the thread.

A cheap way to notify the thread that something happened (useful for, e.g., making thread leave wait_for_any_message() method). External call method.

pop_message(tag)

Pop the latest message with the given tag.

Select the message with the highest priority, and among those the oldest one. If no messages are available, raise threadprop.NoMessageThreadError. Local call method.

process_interrupt(tag, value)

Process a new interrupt.

If the function returns False, the interrupt is put in the corresponding queue. Otherwise, the the message is interrupt to be already, and it gets ‘absorbed’. Local call method, called automatically.

process_message(tag, value)

Process a new message.

If the function returns False, the message is put in the corresponding queue. Otherwise, the the message is considered to be already, and it gets ‘absorbed’. Local call method, called automatically.

remove_stop_notifier(func)

Remove the stop notifier from this controller.

Return True if the notifier was in this thread and is now removed, and False otherwise. Local call method.

request_stop()

Request thread stop (send a stop command).

External call method.

running()

Check if the thread is running

send_interrupt(tag, value, priority=0)

Send an interrupt message to the thread with a given tag, value and priority.

External call method.

send_message(tag, value, priority=0)

Send a message to the thread with a given tag, value and priority.

External call method.

send_multicast(dst='any', tag=None, value=None, src=None, filter_results=True)

Send a multicast to the multicast pool.

By default, the multicast source is the thread’s name. Return result synchronizers for all executed subscribed methods. Local call method.

Parameters:
  • dst (str) – multicast destination; can be a name, "all" (will pass all subscribers’ destination filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" destination).

  • tag (str) – multicast tag.

  • value – multicast value.

  • src (str) – multicast source; can be None (current thread name), a specific name, "all" (will pass all subscribers’ source filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" source).

  • filter_results – if True, filter the results to exclude dummy synchronizers, which correspond to calls which do not return anything

send_multicast_sync(dst='any', tag=None, value=None, src=None, timeout=None, default_result=None, pass_exception=True)

Send a multicast to the multicast pool and synchronize the results, if available.

By default, the multicast source is the thread’s name. Results are collected and synchronized only from the subscriptions which return them (i.e., set return_result=True). Local call method.

Parameters:
  • dst (str) – multicast destination; can be a name, "all" (will pass all subscribers’ destination filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" destination).

  • tag (str) – multicast tag.

  • value – multicast value.

  • src (str) – multicast source; can be None (current thread name), a specific name, "all" (will pass all subscribers’ source filters), or "any" (will only be passed to subscribers specifically subscribed to multicast with "any" source).

  • timeout – synchronization timeout (None means waiting forever)

  • default_result – default result value if synchronization failed (timed out, thread stopped, etc.)

  • pass_exception – if True and the signal processor raised an exception, raise it in this thread as well If pass_exception==True and the returned value represents exception, re-raise it in the caller thread; otherwise, return default.

send_sync(tag, uid)

Send a synchronization signal with the given tag and UID.

This method is rarely invoked directly, and is usually used by synchronizers code (e.g., QThreadNotifier). External call method.

set_func_variable(name, func, use_lock=True)

Set a ‘function’ variable.

Acts as a thread variable to the external user, but instead of reading a stored value, it executed a function instead. Note, that the function is executed in the caller thread (i.e., the thread which tries to access the variable), so use of synchronization methods (commands, signals, locks) is highly advised.

If use_lock==True, then the function call will be wrapped into the usual variable lock, i.e., it won’t run concurrently with other variable access. Local call method.

set_variable(name, value, update=False, notify=False, notify_tag='changed/*', simple=False)

Set thread variable.

Can be called in any thread (controlled or external). If notify==True, send an multicast with the given notify_tag (where "*" symbol is replaced by the variable name). If update==True and the value is a dictionary, update the branch rather than overwrite it. If simple==True, assume that the result is a single atomic variable, in which case the lock is not used; note that in this case the threads waiting on this variable (or branches containing it) will not be notified. Local call method.

sleep(timeout, wake_on_message=False, top_loop=False)

Sleep for a given time (in seconds).

Unlike time.sleep(), constantly checks the event loop for new messages (e.g., if stop or interrupt commands are issued). In addition, if wake_on_message==True, wake up if any message has been received; it this case. return True if the wait has been completed, and False if it has been interrupted by a message. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). If timeout is None, wait forever (usually, until the application is closed, or some interrupt message raises and error). Local call method.

start()

Start the thread.

External call method.

started = <Mock name='mock.QtCore.pyqtSignal()' id='139946557760272'>

This signal is emitted after the thread has started (after the setup code has been executed, before its lifetime state is changed)

stop(code=0, sync=False)

Stop the thread.

If called from the thread, stop immediately by raising a threadprop.InterruptExceptionStop exception. Otherwise, schedule thread stop. If the thread kind is "main", stop the whole application with the given exit code. Otherwise, stop the thread. If sync==True and the thread is not main or current, wait until it is completely stopped. Universal call method.

subscribe_direct(callback, srcs='any', tags=None, dsts='any', filt=None, subscription_priority=0, scheduler=None, return_result=False, sid=None)

Subscribe asynchronous callback to a multicast.

If a multicast is sent, callback is called from the sending thread (not subscribed thread). Therefore, should be used with care. In Qt, analogous to making a signal connection with a direct call. By default, the subscribed destination is the thread’s name. Local call method.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • subscription_priority (int) – subscription priority (higher priority subscribers are called first).

  • scheduler – if defined, multicast call gets scheduled using this scheduler instead of being called directly (which is the default behavior)

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique id and return it).

subscribe_sync(callback, srcs='any', tags=None, dsts='any', filt=None, subscription_priority=0, limit_queue=None, call_interrupt=True, add_call_info=False, return_result=False, sid=None)

Subscribe a synchronous callback to a multicast.

If a multicast is sent, callback is called from the dest_controller thread (by default, thread which is calling this function) via the thread call mechanism (QThreadController.call_in_thread_callback()). In Qt, analogous to making a signal connection with a queued call. By default, the subscribed destination is the thread’s name. Local call method.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • subscription_priority (int) – subscription priority (higher priority subscribers are called first).

  • limit_queue (int) – limits the maximal number of scheduled calls (if the multicast is sent while at least limit_queue callbacks are already in queue to be executed, ignore it) 0 or negative value means no limit (not recommended, as it can increase the queue indefinitely if the multicast rate is high enough)

  • call_interrupt – whether the call is an interrupt (call inside any loop, e.g., during waiting or sleeping), or it should be called in the main event loop

  • add_call_info (bool) – if True, add a fourth argument containing a call information (tuple with a single element, a timestamps of the call).

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique name).

sync_exec_point(point, timeout=None, counter=1)

Wait for the given execution point.

Automatically invoked points include "start" (thread starting), "run" (thread setup and ready to run), "cleanup" (thread stopping is invoked, starting to clean up) and "stop" (thread finished). If timeout is passed, raise threadprop.TimeoutThreadError. counter specifies the minimal number of pre-requisite notify_exec_point() calls to finish the waiting (by default, a single call is enough). Return actual number of notifier calls up to date. External call method.

sync_stop()

Wait until the controller and the thread are stopped.

External call method.

sync_variable(name, pred, timeout=None)

Wait until thread variable with the given name satisfies the condition given by pred.

pred can be a variable values, a container (list, set, tuple) of possible values, or a function which takes one argument (variable value) and returns whether the condition is satisfied. It is executed in the caller thread. External call method.

unsubscribe(sid)

Unsubscribe from a subscription with a given ID.

Note that multicasts which are already emitted but not processed will remain in the queue; if they need to be ignored, it should be handled explicitly. Local call method.

wait_for_any_message(timeout=None, top_loop=False)

Wait for any message (including synchronization messages or pokes).

If timeout is passed, raise threadprop.TimeoutThreadError. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

wait_for_message(tag, timeout=None, top_loop=False)

Wait for a single message with a given tag.

Return value of a received message with this tag. If timeout is passed, raise threadprop.TimeoutThreadError. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Local call method.

wait_for_sync(tag, uid, timeout=None)

Wait for synchronization signal with the given tag and UID.

This method is rarely invoked directly, and is usually used by synchronizers code. If timeout is passed, raise threadprop.TimeoutThreadError. Local call method.

wait_until(check, timeout=None, top_loop=False)

Wait until a given condition is true.

Condition is given by the check function, which is called after every new received message and should return True if the condition is met. If top_loop==True, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). If timeout is passed, raise threadprop.TimeoutThreadError. Local call method.

pylablib.core.thread.controller.get_controller(name=None, sync=True, timeout=None, sync_point=None)[source]

Find a controller with a given name.

If name is not supplied, yield current controller instead. If name is of int type, interpret it as a thread id. If the controller is not present and sync==True, wait (with the given timeout) until the controller is running; otherwise, raise error if the controller is not running. If sync_point is not None, synchronize to the thread sync_point point (by default, "run", i.e., after the setup is done) before returning.

pylablib.core.thread.controller.sync_controller(name, sync_point='run', timeout=None)[source]

Find a controller with a given name and synchronize to the given point.

If the controller is not present and sync==True, wait (with the given timeout) until the controller is running; otherwise, raise error if the controller is not running. Analogous to get_controller(name, sync=True, timeout=timeout, sync_point=sync_point).

pylablib.core.thread.controller.get_gui_controller(sync=False, timeout=None, create_if_missing=True)[source]

Get GUI thread controller.

If the controller is not present and sync==True, wait (with the given timeout) until the controller is running. If the controller is still not present and create_if_missing==True, initialize the standard GUI controller.

pylablib.core.thread.controller.stop_controller(name=None, code=0, sync=True, require_controller=False)[source]

Stop a controller with a given name (current controller by default).

code specifies controller exit code (only applies to the main thread controller). If require_controller==True and the controller is not present, raise and error; otherwise, do nothing. If sync==True, wait until the controller is stopped.

pylablib.core.thread.controller.stop_all_controllers(sync=True, concurrent=True, stop_self=True)[source]

Stop all running threads.

If sync==True, wait until the all of the controller are stopped. If sync==True and concurrent==True stop threads in concurrent manner (first issue stop messages to all of them, then wait until all are stopped). If sync==True and concurrent==False stop threads in consecutive manner (wait for each thread to stop before stopping the next one). If stop_self==True stop current thread after stopping all other threads.

pylablib.core.thread.controller.stop_app(code=0, sync=False)[source]

Initialize stopping the application.

Do this either by stopping the GUI controller (if it exists), or by stopping all controllers. If sync is True and the thread is not the main one, wait at this point until the process is stopped during the app shutdown; otherwise, the execution will continue as normal, and the thread will be stopped at a later time during the app shutdown.

pylablib.core.thread.controller.restart_app(code=0, sync=False)[source]

Restart the application.

Equivalent to stop_app() followed by the scrip restart. If sync is True and the thread is not the main one, wait at this point until the process is stopped during the app shutdown; otherwise, the execution will continue as normal, and the thread will be stopped at a later time during the app shutdown.

pylablib.core.thread.multicast_pool module

class pylablib.core.thread.multicast_pool.TMulticast(src, tag, value)

Bases: tuple

src
tag
value
class pylablib.core.thread.multicast_pool.MulticastPool[source]

Bases: object

Multicast dispatcher (somewhat similar in functionality to Qt signals).

Manages dispatching multicasts between sources and destinations (callback functions). Each multicast has defined source, destination (both can also be "all" or "any", see methods descriptions for details), tag and value. Any thread can send a multicast or subscribe for a multicast with given filters (source, destination, tag, additional filters). If a multicast is emitted, it is checked against filters for all subscribers, and the passing ones are then called.

subscribe_direct(callback, srcs='any', dsts='any', tags=None, filt=None, priority=0, scheduler=None, return_result=False, sid=None)[source]

Subscribe an asynchronous callback to a multicast.

If a multicast is sent, callback is called from the sending thread (not subscribed thread). Therefore, should be used with care. In Qt, analogous to making a signal connection with a direct call.

Parameters:
  • callback – callback function, which takes 3 arguments: source, tag, and value.

  • srcs (str or [str]) – multicast source name or list of source names to filter the subscription; can be "any" (any source) or "all" (only multicasts specifically having "all" as a source).

  • dsts (str or [str]) – multicast destination name or list of destination names to filter the subscription; can be "any" (any destination) or "all" (only source specifically having "all" as a destination).

  • tags – multicast tag or list of tags to filter the subscription (any tag by default); can also contain Unix shell style pattern ("*" matches everything, "?" matches one symbol, etc.)

  • filt (callable) – additional filter function which takes 4 arguments: source, destination, tag, and value, and checks whether multicast passes the requirements.

  • priority (int) – subscription priority (higher priority subscribers are called first).

  • scheduler – if defined, multicast call gets scheduled using this scheduler instead of being called directly (which is the default behavior)

  • return_result – if True, use a result synchronizer to return the result of the subscribed call; otherwise, ignore the result

  • sid (int) – subscription ID (by default, generate a new unique name).

Returns:

subscription ID, which can be used to unsubscribe later.

unsubscribe(sid)[source]

Unsubscribe from a subscription with a given ID

send(src, dst='any', tag=None, value=None)[source]

Send a multicast.

Parameters:
  • src (str) – multicast source; can be a name, "all" (will pass all subscribers’ source filters), or "any" (will only be passed to subscribers specifically subscribed to multicasts with "any" source).

  • dst (str) – multicast destination; can be a name, "all" (will pass all subscribers’ destination filters), or "any" (will only be passed to subscribers specifically subscribed to multicasts with "any" destination).

  • tag (str) – multicast tag.

  • value – multicast value.

pylablib.core.thread.notifier module

class pylablib.core.thread.notifier.ISkippableNotifier(skippable=False)[source]

Bases: object

Generic skippable notifier.

The main methods are wait() (wait until the event happened) and notify() (notify that the event happened). Only calls underlying waiting and notifying methods once, duplicate calls are ignored.

Parameters:

skippable (bool) – if True, allows for skippable wait events (if notify() is called before wait(), neither methods are actually called).

wait(*args, **kwargs)[source]

Wait for the notification.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called after notify(), return immediately.

notify(*args, **kwargs)[source]

Notify the waiting process.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called before wait(), return immediately.

waiting()[source]

Check if waiting is in progress

done_wait()[source]

Check if waiting is done

success_wait()[source]

Check if waiting is done successfully

done_notify()[source]

Check if notifying is done

waiting_state()[source]
notifying_state()[source]

pylablib.core.thread.profile module

pylablib.core.thread.profile.start(reset=True)[source]

Start yappi profile logging.

If reset==True, reset the stats.

pylablib.core.thread.profile.reset()[source]

Reset yappi profiling stats

pylablib.core.thread.profile.stop()[source]

Stop yappi profiling

pylablib.core.thread.profile.get_stats()[source]

Get yappi profiling stats.

Return tuple ((ttime,wtime), (threads,ctls)). Here ttime and wtime are total execution time (sum of all thread times) and the wall time (since the last reset) respectively. threads are yappi-generated stats, and ctls is the list [(name,ctl)] with the controller names and thread controllers, which are ordered in the same way as threads (for any non-controlled or stopped thread these are set to None).

pylablib.core.thread.profile.print_stats(nfunc=None, ntotfunc=None, min_func_frac=0.001)[source]

Print yappi profiling stats.

nfunc is the number of top (most expensive) functions to print per each thread, ntotfunc is the number of global top function to print; None for either means that they are not printed. min_func_frac specifies the minimal fraction of the total time for which the function stats are still printed (to prevent lost of printouts for “cheap” threads).

pylablib.core.thread.synchronizing module

class pylablib.core.thread.synchronizing.QThreadNotifier(skippable=True)[source]

Bases: ISkippableNotifier

Wait-notify thread synchronizer for controlled Qt threads based on notifier.ISkippableNotifier.

Like notifier.ISkippableNotifier, the main functions are ISkippableNotifier.wait() (wait in a message loop until notified or until timeout expires) and ISkippableNotifier.notify() (notify the waiting thread). Both of these can only be called once and will raise and error on repeating calls. Along with notifying a variable can be passed, which can be accessed using get_value() and get_value_sync().

Parameters:

skippable (bool) – if True, allows for skippable wait events (if ISkippableNotifier.notify() is called before ISkippableNotifier.wait(), neither methods are actually called).

get_value()[source]

Get the value passed by the notifier (doesn’t check if it has been passed already)

get_value_sync(timeout=None)[source]

Wait (with the given timeout) for the value passed by the notifier

done_notify()

Check if notifying is done

done_wait()

Check if waiting is done

notify(*args, **kwargs)

Notify the waiting process.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called before wait(), return immediately.

notifying_state()
success_wait()

Check if waiting is done successfully

wait(*args, **kwargs)

Wait for the notification.

Can only be called once per notifier lifetime. If the notifier allows skipping, and this method is called after notify(), return immediately.

waiting()

Check if waiting is in progress

waiting_state()
class pylablib.core.thread.synchronizing.QMultiThreadNotifier[source]

Bases: object

Wait-notify thread synchronizer that can be used for multiple threads and called multiple times.

Performs similar function to conditional variables. The synchronizer has an internal counter which is increased by 1 every time it is notified. The wait functions have an option to wait until the counter reaches the specific counter value (usually, 1 above the last wait call).

wait(state=1, timeout=None)[source]

Wait until notifier counter is equal to at least state

Return current counter state plus 1, which is the next smallest value resulting in waiting.

wait_until(condition, timeout=None)[source]

Wait until condition is met.

condition is a function which is called (in the waiting thread) every time the synchronizer is notified. If it return non-False, the waiting is complete and its result is returned.

notify()[source]

Notify all waiting threads

fail()[source]

Mark notifier as fails

Fails all waiting notifiers. All subsequent wait calls raise an error

class pylablib.core.thread.synchronizing.QLockNotifier[source]

Bases: object

Resource lock.

Behaves similarly to the regular lock, but waiting is done in the message loop, which still allows interrupts.

acquire(timeout=None)[source]
release()[source]

pylablib.core.thread.threadprop module

exception pylablib.core.thread.threadprop.ThreadError(msg=None)[source]

Bases: RuntimeError

Generic thread error

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.NoControllerThreadError(msg=None)[source]

Bases: ThreadError

Thread error for a case of thread having no controllers

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.DuplicateControllerThreadError(msg=None)[source]

Bases: ThreadError

Thread error for a case of a duplicate thread controller

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.TimeoutThreadError(msg=None)[source]

Bases: ThreadError, TimeoutError

Thread error for a case of a wait timeout

add_note()

Exception.add_note(note) – add a note to the exception

args
characters_written
errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.NoMessageThreadError(msg=None)[source]

Bases: ThreadError

Thread error for a case of trying to get a non-existing message

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.SkippedCallError(msg=None)[source]

Bases: ThreadError

Thread error for a case of external call getting skipped (unscheduled)

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.InterruptException(msg=None)[source]

Bases: Exception

Generic interrupt exception (raised by some function to signal interrupts from other threads)

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pylablib.core.thread.threadprop.InterruptExceptionStop(msg=None)[source]

Bases: InterruptException

Interrupt exception denoting thread stop request

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

pylablib.core.thread.threadprop.get_app()[source]

Get current application instance

pylablib.core.thread.threadprop.get_gui_thread()[source]

Get main (GUI) thread, or None if application is not running

pylablib.core.thread.threadprop.is_gui_running()[source]

Check if GUI is running

pylablib.core.thread.threadprop.is_gui_thread()[source]

Check if the current thread is the one running the GUI loop

pylablib.core.thread.threadprop.current_controller(require_controller=True)[source]

Get controller of the current thread.

If the current thread has not controller and `require_controller==True`, raise an error; otherwise, return None.

pylablib.core.thread.utils module

class pylablib.core.thread.utils.ReadChangeLock[source]

Bases: object

Lock based on condition variables which handles a state which can be read or changed.

Any number of threads can read simultaneously, but changing is incompatible with other reading or changing.

can_read()[source]

Check if the state can be read

can_change()[source]

Check if the state can be changed

reading()[source]

Context manager denoting reading event

changing()[source]

Context manager denoting changing event

Module contents