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).
- 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), raisethreadprop.NoControllerThreadError
; otherwise, return default. Iferror_on_skip==True
and the call was skipped (e.g., due to full call queue), raisethreadprop.SkippedCallError
; otherwise, return default. Ifpass_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)
- 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_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
)
- 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 threadsresult_synchronizer – result synchronizer object; can be
None
(create newQCallResultSynchronizer
),"async"
(no result synchronization), or aQCallResultSynchronizer
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 (orNone
if call failed); otherwise, pass no arguments. Ifcall_on_exception==True
, call it even if the original call raised an exception. Ifcall_on_unschedule==True
, call it for any call unscheduling event, including usingskip()
orfail()
methods (this effectively ignores call_on_exception, since the callback is called regardless of the exception). Iffront==True
, add the callback in the front of the line (executes first).
- 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 aQScheduledCall
with appropriate parameters, andschedule()
, which takes a call and schedules it. Theschedule()
method should returnTrue
if the scheduling was successful (at least, for now), andFalse
otherwise.- Parameters:
call_info_argname – if not
None
, supplies a name of a keyword argument via which call info (generated bybuild_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=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 argumentscallback_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 successfulsync_result – if
True
, the call has a default result synchronizer; otherwise, no synchronization is made.
- 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 byQScheduler.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 argumentscallback_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 successfulsync_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.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()
returnsFalse
); 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 byQScheduler.build_call_info()
) is passed on function call
- Methods to overload:
can_schedule()
: check if the call can be scheduledcall_added()
: called when a new call has been added to the queuecall_popped()
: called when a call has been removed from the queue (either for execution, or for skipping)
- call_popped(call, idx)[source]
Called whenever call has been removed from the queue
idx determines the call position within the queue.
- 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).
- 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 argumentscallback_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 successfulsync_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 parameterarg_name
supplied to the methodon_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 byQScheduler.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)
- call_popped(call, idx)[source]
Called whenever call has been removed from the queue
idx determines the call position within 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 argumentscallback_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 successfulsync_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 byQScheduler.build_call_info()
) is passed on function call
- call_popped(call, idx)[source]
Called whenever call has been removed from the queue
idx determines the call position within 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 argumentscallback_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 successfulsync_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, returnTrue
.
- 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).
- 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 byQScheduler.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=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 argumentscallback_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 successfulsync_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 byQScheduler.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=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 argumentscallback_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 successfulsync_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'>
- 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 inprocess_message()
and remote calls),"run"
(thread executesrun()
method and quits after it is complete), or"main"
(can only be created in the main GUI thread)multicast_pool –
MulticastPool
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 ifkind=="run"
)process_message()
: function that takes 2 arguments (tag and value) of the message and processes it; returnsTrue
if the message has been processed andFalse
otherwise(in which case it is stored and can be recovered via
wait_for_message()
/pop_message()
); by default, always returnFalse
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 (afteron_start()
is executed)finished
: emitted on thread finish (beforeon_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 anycall_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
. Iftop_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
. Iftop_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. Iftop_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, raisethreadprop.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, ifwake_on_message==True
, wake up if any message has been received; it this case. returnTrue
if the wait has been completed, andFalse
if it has been interrupted by a message. Iftop_loop==True
, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Iftimeout 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 resultsid (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 resultsid (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 Ifpass_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). Ifupdate==True
and the value is a dictionary, update the branch rather than overwrite it. Ifsimple==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.
- 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. Ifcopy_branch==True
and the variable is aDictionary
branch, return its copy to ensure that it stays unaffected on possible further variable assignments. Ifsimple==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.
- 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. Ifsync==True
and the thread is not main or current, wait until it is completely stopped. Universal 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.
- 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, raisethreadprop.TimeoutThreadError
. counter specifies the minimal number of pre-requisitenotify_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). ReturnTrue
if the thread is still running and the notifier is added, andFalse
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, andFalse
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 (methodQCallResultSynchronizer.get_value_sync()
). If callback is notNone
, call it after the function is successfully executed (from the target thread), with a single parameter being function result. Ifpass_exception==True
and func raises an exception, re-raise it in the caller thread (applies only ifsync==True
). Ifsilent==True
and func raises an exception, silence it in the execution thread and only re-raise it in the caller thread; note that ifpass_exception==False
andsilent==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). Ifinterrupt==True
, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. Iferror_on_stopped==True
and the controlled thread is stopped before it executed the call, raisethreadprop.NoControllerThreadError
; otherwise, return default_result. Ifsame_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()
methodkwargs – keyword args supplied to
setup_task()
methodmulticast_pool –
MulticastPool
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 toctl.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 toctl.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 toctl.call_command("comm",args,kwargs,sync="delayed")
- cs
synchronous command accessor, which makes calls more function-like;
ctl.cs.comm(*args,**kwarg)
is equivalent toctl.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 towith 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 toctl.call_command("comm",*args,**kwargs)
, which is often also equivalent toctl.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 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
- 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.
- 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 raisesStopIteration
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 timeyield
statement is encountered, the execution is suspended for period seconds (specified instart_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. Ifstop==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. Ifrestart==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.
- 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. Ifstop_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 usingrestart_batch_job()
, as it will be removed after the stopping before the restart. All the parameters are the same as foradd_batch_job()
andstart_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
. Iftext is not None
, it specifies new status text stored in"status/"+kind+"_text"
. Ifnotify==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 ignoredlimit_queue – command call queue limit;
None
means no limiton_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 resultsid (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. Ifsync==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. Ifsync=="delayed"
, returnQCallResultSynchronizer
object which can be used to wait for and read the command result; otherwise, returnNone
. In thesync==True
case, ifignore_errors==True
, ignore all possible problems with the call (controller stopped, call raised an exception, call was skipped) and returnNone
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. Ifsync=="delayed"
, returnQCallResultSynchronizer
object which can be used to wait for and read the command result; otherwise, returnNone
. priority sets the call priority (by default, the same as the standard commands). In thesync==True
case, ifignore_errors==True
, ignore all possible problems with the call (controller stopped, call raised an exception, call was skipped) and returnNone
instead; otherwise, these problems raise exceptions in the caller thread. Ifsame_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). ReturnTrue
if the thread is still running and the notifier is added, andFalse
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 anycall_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 (methodQCallResultSynchronizer.get_value_sync()
). If callback is notNone
, call it after the function is successfully executed (from the target thread), with a single parameter being function result. Ifpass_exception==True
and func raises an exception, re-raise it in the caller thread (applies only ifsync==True
). Ifsilent==True
and func raises an exception, silence it in the execution thread and only re-raise it in the caller thread; note that ifpass_exception==False
andsilent==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). Ifinterrupt==True
, method can be called inside any control loop (either main loop, or during waiting); otherwise, only call it in the top loop. Iferror_on_stopped==True
and the controlled thread is stopped before it executed the call, raisethreadprop.NoControllerThreadError
; otherwise, return default_result. Ifsame_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. Ifcopy_branch==True
and the variable is aDictionary
branch, return its copy to ensure that it stays unaffected on possible further variable assignments. Ifsimple==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, andFalse
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 Ifpass_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). Ifupdate==True
and the value is a dictionary, update the branch rather than overwrite it. Ifsimple==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, ifwake_on_message==True
, wake up if any message has been received; it this case. returnTrue
if the wait has been completed, andFalse
if it has been interrupted by a message. Iftop_loop==True
, treat the waiting as the top message loop (i.e., any top loop message or signal can be executed here). Iftimeout 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. Ifsync==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 resultsid (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 resultsid (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, raisethreadprop.TimeoutThreadError
. counter specifies the minimal number of pre-requisitenotify_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
. Iftop_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
. Iftop_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. Iftop_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, raisethreadprop.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 andsync==True
, wait (with the given timeout) until the controller is running; otherwise, raise error if the controller is not running. If sync_point is notNone
, 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 toget_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 andcreate_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. Ifsync==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. Ifsync==True
andconcurrent==True
stop threads in concurrent manner (first issue stop messages to all of them, then wait until all are stopped). Ifsync==True
andconcurrent==False
stop threads in consecutive manner (wait for each thread to stop before stopping the next one). Ifstop_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 isTrue
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 resultsid (int) – subscription ID (by default, generate a new unique name).
- Returns:
subscription ID, which can be used to unsubscribe later.
- 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) andnotify()
(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 (ifnotify()
is called beforewait()
, 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.
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.get_stats()[source]
Get yappi profiling stats.
Return tuple
((ttime,wtime), (threads,ctls))
. Herettime
andwtime
are total execution time (sum of all thread times) and the wall time (since the last reset) respectively.threads
are yappi-generated stats, andctls
is the list[(name,ctl)]
with the controller names and thread controllers, which are ordered in the same way asthreads
(for any non-controlled or stopped thread these are set toNone
).
- 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 areISkippableNotifier.wait()
(wait in a message loop until notified or until timeout expires) andISkippableNotifier.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 usingget_value()
andget_value_sync()
.- Parameters:
skippable (bool) – if
True
, allows for skippable wait events (ifISkippableNotifier.notify()
is called beforeISkippableNotifier.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.
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_gui_thread()[source]
Get main (GUI) thread, or
None
if application is not running