Package: cs.result
Result and friends: various subclassable classes for deferred delivery of values.Latest release 20231221:
Doc update.AResultis the base class for several callable subclasses
which will receive values at a later point in time,
and can also be used standalone without subclassing.A call to aResultwill block until the value is received or theResultis cancelled,
which will raise an exception in the caller.
AResultmay be called by multiple users, before or after the value has been delivered;
if the value has been delivered the caller returns with it immediately.
AResult's state may be inspected (pending, running, ready, cancelled).
Callbacks can be registered via aResult's .notify method.An incompleteResultcan be told to call a function to compute its value;
the function return will be stored as the value unless the function raises an exception,
in which case the exception information is recorded instead.
If an exception occurred, it will be reraised for any caller of theResult.Trite example:R = Result(name="my demo")Thread 1:# this blocks until the Result is ready
value = R()
print(value)
# prints 3 once Thread 2 (below) assigns to itThread 2:R.result = 3Thread 3:value = R()
# returns immediately with 3You can also collect multipleResults in completion order using thereport()function:Rs = [ ... list of Results of whatever type ... ]
...
for R in report(Rs):
    x = R()     # collect result, will return immediately because
                # the Result is complete
    print(x)    # print resultFunctionafter(Rs, R, func, *a, **kw)After the completion ofRscallfunc(*a,**kw)and return
its result viaR; return theResultobject.Parameters:Rs: an iterable of Results.R: aResultto collect to result of callingfunc.
IfNone, one will be created.func,a,kw: a callable and its arguments.Functionbg(func, *a, **kw)Dispatch aThreadto runfunc, return aResultto collect its value.Parameters:_name: optional name for theResult, passed to the initialiser_extra: optional extra data for theResult, passed to the initialiserOther parameters are passed tofunc.Functioncall_in_thread(func, *a, **kw)Runfunc(*a,**kw)in a separateThreadvia the@in_threaddecorator.
Return or exception is as for the original function.ClassCancellationError(builtins.Exception, builtins.BaseException)Raised when accessingresultorexc_infoafter cancellation.MethodCancellationError.__init__(self, message=None, **kw):
Initialise theCancellationError.The optionalmessageparameter (default"cancelled")
is set as themessageattribute.
Other keyword parameters set their matching attributes.Functionin_thread(func)Decorator to evaluatefuncin a separateThread.
Return or exception is as for the original function.This exists to step out of the currentThread'sthread
local context, such as a database transaction associated
with Django's implicit per-Threaddatabase context.ClassOnDemandFunction(Result, cs.fsm.FSM, cs.gvutils.DOTNodeMixin)Wrap a callable, run it when required.ClassOnDemandResult(Result, cs.fsm.FSM, cs.gvutils.DOTNodeMixin)Wrap a callable, run it when required.Functionreport(LFs)Generator which yields completedResults.This is a generator that yieldsResults as they complete,
useful for waiting for a sequence ofResults
that may complete in an arbitrary order.ClassResult(cs.fsm.FSM, cs.gvutils.DOTNodeMixin)Base class for asynchronous collection of a result.
This is used to makeResult,OnDemandFunctions,LateFunctions
and other objects with asynchronous termination.In addition to the methods below, for each state value such
asself.PENDINGthere is a corresponding attributeis_pendingtesting whether theResultis in that state.MethodResult.__init__(self, name=None, lock=None, result=None, state=None, extra=None):
Base initialiser forResultobjects and subclasses.Parameter:name: optional parameter naming this object.lock: optional locking object, defaults to a newthreading.Lock.result: if notNone, prefill the.resultproperty.extra: an optional mapping of extra information to
associate with theResult, useful to provide context
when collecting the result; theResulthas a public
attribute.extrawhich is anAttrableMappingto hold
this information.ClassResultSet(builtins.set)Asetsubclass containingResults,
on which one may iterate asResults complete.Release LogRelease 20231221:
Doc update.Release 20231129:
Result.del: issue a warning about no collection instead of raising an exception.Release 20230331:
Result.join: access self._result instead of the property.Release 20230212:Result._complete: release self._get_lock before firing the event, as the event is what fires the notifiers.Result.notify: when we make a direct notifier call, call the notifier outside the lock and remember to set self.collected=True.Result: new post_notify() method to queue a function of the Result.result, returning a Result for the completion of the post function.Release 20221207:
CancellationError: accept keyword arguments, apply as attributes.Release 20221118:CancellationError: rename msg to message.Result.run_func_in_thread: new method to run an arbitrary function in a separate Thread and return it via the Result.New @in_thread decorator to cause a function to run in a separate Thread using Result.run_in_thread.New call_in_thread to run an arbitrary function in a distinct Thread.@in_thread: expose the original function as the decorated function's .direct attribute.Release 20220918:
OnDemandResult: modern "pending" check.Release 20220805:
Result now subclasses cs.fsm.FSM.Release 20220311:Result: class local Seq instance.Result.call: thread safe runtime check of self.state==pending.New Task and @task decorator, prototype for rerunnable blocking chaining tasks scheme - very alpha.Release 20210420:
Update dependencies, add docstring.Release 20210407:
New ResultSet(set) class, with context manager and wait methods, and whoseiteriterates completed Results.Release 20210123:
bg: accept optional _extra parameter for use by the Result.Release 20201102:
Result: now .extra attribute for associated data and a new optional "extra" parameter in the initialiser.Release 20200521:OnDemandResult: bugfixes and improvements.Result.bg: accept optional _name parameter to specify the Result.name.Release 20191007:Simplify ResultState definition.Result.bg: use cs.threads.bg to dispatch the Thread.Release 20190522:Result.callnow accepts an optional callable and args.Result.call: set the Result state to "running" before dispatching the function.Rename OnDemandFunction to OnDemandResult, keep old name around for compatibility.Result._complete: also permitted if state==cancelled.Release 20190309:
Small bugfix.Release 20181231:Result.call: report baser exceptions than BaseException.Drop _PendingFunction abstract class.Release 20181109.1:
DISTINFO update.Release 20181109:Derive CancellationError from Exception instead of RuntimeError, fix initialiser.Rename AsynchState to ResultState and make it an Enum.Make Results hashable and comparable for equality for use as mapping keys: equality is identity.New Result.collected attribute, set true if .result or .exc_info are accessed, logs an error if Result.delis called when false, may be set true externally if a Result is not required.Dropfinalparameter; never used and supplanted by Result.notify.Result.join: return the .result and .exc_info properties in order to mark the Result as collected.Result: set .collected to True when a notifier has been called successfully.Bugfix Result.cancel: apply the new cancelled state.Release 20171231:Bugfix Result.call to catch BaseException instead of Exception.New convenience function bg(func) to dispatchfuncin a separate Thread and return a Result to collect its value.Release 20171030.1:
Fix module requirements specification.Release 20171030:
New Result.bg(func, *a, **kw) method to dispatch function in separate Thread to compute the Result value.Release 20170903:
rename cs.asynchron to cs.result