Package: cs.threads
Thread related convenience classes and functions.Latest release 20231129:HasThreadState.thread_states:policy change: the default now makes a mapping only for this class, not for all HasThreadState subclasses, on the premise that this class can manage use of other classes if required.HasThreadState: new bg() class method like Thread() but also starting the Thread.ClassAdjustableSemaphoreA semaphore whose value may be tuned after instantiation.Functionbg(func, daemon=None, name=None, no_start=False, no_logexc=False, thread_class=None, thread_states=None, args=None, kwargs=None)Dispatch the callablefuncin its ownThread;
return theThread.Parameters:func: a callable for theThreadtarget.daemon: optional argument specifying the.daemonattribute.name: optional argument specifying theThreadname,
default: the name offunc.no_logexc: if false (defaultFalse), wrapfuncin@logexc.no_start: optional argument, defaultFalse.
If true, do not start theThread.thread_class: theThreadfactory, defaultHasThreadState.Threadthread_states: passed tothethread_classfactoryargs,kwargs: passed to theThreadconstructorClassHasThreadState(cs.context.ContextManagerMixin)A mixin for classes with acs.threads.ThreadStateinstance as.stateproviding a context manager which pushescurrent=selfonto that state
and adefault()class method returningcls.perthread_state.currentas the default instance of that class.NOTE: the documentation here refers tocls.perthread_state, but in
fact we honour thecls.THREAD_STATE_ATTRattribute to name
the state attribute which allows perclass state attributes,
and also use with classes which already use.perthread_statefor
another purpose.NOTE:HasThreadState.Threadis aclassmethod whose default
is to push state for all activeHasThreadStatesubclasses.
Contrast withHasThreadState.bgwhich is an _instance_method
whose default is to push state for just that instance.
The top levelcs.threads.bgfunction callsHasThreadState.Threadto obtain itsThread.Functionjoinif(T: threading.Thread)CallT.join()ifTis not the currentThread.Unlikethreading.Thread.join, this function is a no-op ifTis the current `Thread.The use case is situations such as the shutdown phase of theMultiOpenMixin.startup_shutdowncontext manager. Because
the "initial open" startup phase is not necessarily run in
the same thread as the "final close" shutdown phase, it is
possible for example for a workerThreadto execute the
shutdown phase and try to join itself. Using this function
allows that scenario.ClassLockableMixinTrite mixin to control access to an object via its._lockattribute.
Exposes the._lockas the property.lock.
Presents a context manager interface for obtaining an object's lock.Functionlocked(*da, **dkw)A decorator for instance methods that must run within a lock.Decorator keyword arguments:initial_timeout:
the initial lock attempt timeout;
if this is>0and exceeded a warning is issued
and then an indefinite attempt is made.
Default:2.0slockattr:
the name of the attribute ofselfwhich references the lock object.
Default'_lock'Functionlocked_property(*da, **dkw)A thread safe property whose value is cached.
The lock is taken if the value needs to computed.The default lock attribute is._lock.
The default attribute for the cached value is._funcnamewherefuncnameisfunc.__name__.
The default "unset" value for the cache isNone.Functionmonitor(*da, **dkw)Turn a class into a monitor, all of whose public methods are@locked.This is a simple approach which requires class instances to have a._lockwhich is anRLockor compatible
because methods may naively call each other.Parameters:attrs: optional iterable of attribute names to wrap in@locked.
If omitted, all names commencing with a letter are chosen.initial_timeout: optional initial lock timeout, default10.0s.lockattr: optional lock attribute name, default'_lock'.Only attributes satifyinginspect.ismethodare wrapped
because@lockedrequires access to the instance._lockattribute.ClassPriorityLockA priority based mutex which is acquired by and released to waiters
in priority order.The initialiser sets a default priority, itself defaulting to0.Theacquire()method accepts an optionalpriorityvalue
which specifies the priority of the acquire request;
lower values have higher priorities.acquirereturns a newPriorityLockSubLock.Note that internally this allocates athreading.Lockper acquirer.Whenacquireis called, if thePriorityLockis taken
then the acquirer blocks on their personalLock.Whenrelease()is called the highest priorityLockis released.Within a priority levelacquires are served in FIFO order.Used as a context manager, the mutex is obtained at the default priority.
Thepriority()method offers a context manager
with a specified priority.
Both context managers return thePriorityLockSubLockallocated by theacquire.MethodPriorityLock.__init__(self, default_priority=0, name=None):
Initialise thePriorityLock.Parameters:default_priority: the defaultacquirepriority,
default0.name: optional identifying nameClassPriorityLockSubLock(PriorityLockSubLock, builtins.tuple)The record for the per-acquirerLockheld byPriorityLock.acquire.ClassState(_thread._local)AThreadlocal object with attributes
which can be used as a context manager to stack attribute values.Example:from cs.threads import ThreadState

S = ThreadState(verbose=False)

with S(verbose=True) as prev_attrs:
    if S.verbose:
        print("verbose! (formerly verbose=%s)" % prev_attrs['verbose'])MethodState.__init__(self, **kw):
Initiale theThreadState, providing the per-Thread initial values.ClassThreadState(_thread._local)AThreadlocal object with attributes
which can be used as a context manager to stack attribute values.Example:from cs.threads import ThreadState

S = ThreadState(verbose=False)

with S(verbose=True) as prev_attrs:
    if S.verbose:
        print("verbose! (formerly verbose=%s)" % prev_attrs['verbose'])MethodThreadState.__init__(self, **kw):
Initiale theThreadState, providing the per-Thread initial values.Functionvia(cmanager, func, *a, **kw)Return a callable that calls the suppliedfuncinside a
with statement using the context managercmanager.
This intended use case is aimed at deferred function calls.Release LogRelease 20231129:HasThreadState.thread_states:policy change: the default now makes a mapping only for this class, not for all HasThreadState subclasses, on the premise that this class can manage use of other classes if required.HasThreadState: new bg() class method like Thread() but also starting the Thread.Release 20230331:HasThreadState: new thread_states() method to snapshot the current states.HasThreadState: new with_thread_states() context manager to apply a set of states.HasThreadState: rename the default state from .state to .perthread_state.HasThreadState.enter_exit: pass cls._HasThreadState_lock to stackset as the modification guard lock, prevents race in thread_states.Rename State to ThreadState, which how I always use it anyway, and leave a compatibility name behind.New joinif(Thread) method to join a Thread unless we are that Thread - this is because MultiOpenMixin.startup_shutdown stuff may run the shutdown in a differ Thread from that which ran the startup.@uses_runstate: use the prevailing RunState or create one.Drop Python 2 support.Release 20230212:HasThreadState: maintain a set of the HasThreadState classes in use.New HasThreadState.Thread class factory method to create a new Thread with the current threads states at time of call instantiated in the new Thread.bg: new no_context=False parameter to suppress use of HasThreadState.Thread to create the new Thread.Release 20230125:
New HasThreadState mixin for classes with a state=State() attribute to provide a cls.default() class method for the default instance and a context manager to push/pop self.state.current=self.Release 20221228:Get error and warning from cs.gimmicks, breaks circular import with cs.logutils.Late import of cs.logutils.LogTime to avoid circular import.Release 20221207:
Small bug fix.Release 20221118:
REMOVE WorkerThreadPool, pulls in too many other things and was never used.Release 20211208:
bg: do not pass the current Pfx prefix into the new Thread, seems to leak and grow.Release 20210306:
bg: include the current Pfx prefix in the thread name and thread body Pfx, obsoletes cs.pfx.PfxThread.Release 20210123:
New @monitor class decorator for simple RLock based reentrance protection.Release 20201025:@locked: bump the default warning timeout to 10s, was firing too often.New State class for thread local state objects with default attribute values and a stackingcallcontext manager.Release 20200718:
@locked: apply the interiordocto the wrapper.Release 20200521:
@locked_property: decorate with @cs.deco.decorator to support keyword arguments.Release 20191102:
@locked: report slow-to-acquire locks, add initial_timeout and lockattr decorator keyword parameters.Release 20190923.2:
Fix annoying docstring typo.Release 20190923.1:
Docstring updates.Release 20190923:
Remove dependence on cs.obj.Release 20190921:
New PriorityLock class for a mutex which releases in (priority,fifo) order.Release 20190812:
bg: compute default name before wrappingfuncin @logexc.Release 20190729:
bg: provide defaultname, run callable inside Pfx, add optional no_logexc=False param preventing @logec wrapper if true.Release 20190422:
bg(): new optionalno_start=Falsekeyword argument, preventing Thread.start if trueRelease 20190102:Drop some unused classes.New LockableMixin, presenting a context manager and a .lock property.Release 20160828:
Use "install_requires" instead of "requires" in DISTINFO.Release 20160827:Replace bare "excepts" with "except BaseException".Doc updates. Other minor improvements.Release 20150115:
First PyPI release.