U
|
Z ±dÊ ã @ sL d dl Z d dlZd dlZd dlZd dlZd dlZd dlmZ d dlm Z d dl
|
Z
|
d dl Z d dl m Z d dlmZ d dlmZ d dlmZmZ d dlmZ d dlZd d lmZmZmZ d d
|
l m Z d d l m Z m Z m!Z!m"Z" d d l#m$Z$m%Z% d dl&m'Z'm(Z(m)Z) d dl*m+Z+m,Z,m-Z- d dl.m/Z/m0Z0 d dl1m2Z2m3Z3m4Z4m5Z5m6Z6m7Z7 d dl8m9Z9 d dl:m;Z; d dl<m=Z= ddl>m?Z? ddl@mAZAmBZBmCZC ejDdk rd dlEmFZF dZGeH ZIdd ZJd ZKe L¡ ZMd d ZNeN ZOejPd d d!G d"d# d#ZQG d$d% d%e jRZSd&d' ZTejPd d d(G d)d* d*ZUejPd d d(G d+d, d,ZVd-ZWejPd d d d.G d/d0 d0eAd1ZXejPd d d d2G d3d4 d4ZYejPG d5d6 d6ZZdgd7d8Z[G d9d: d:eBd1Z\ejPd d d d d;G d<d= d=eBd1Z]G d>d? d?ej^Z_e_ Z`ejPd d@G dAdB dBZaejPd d d dCG dDdE dEZbejPd d d dCG dFdG dGZcdHdI ZdddJd d dKdLdMZedd ddJd d dNdOdPZfdQZgdhdRdSZhG dTdU dUZiei ZjdVdW ZkdXdY ZldZd[ Zmd\d] Znejod^krÔd d_lpmqZr d d`lsT ndejodaksòesetedbrd dclumvZr d d`lwT n0eseteddr0d delxmyZr d d`lzT ne{dfd d`l|T d d`l}T dS )ié N)Údeque)Úcontextmanager)Ú copy_context)Úinf)Ú perf_counter)ÚCallableÚ TYPE_CHECKING)Úcurrent_async_library_cvar)ÚheapifyÚheappopÚheappush)Ú
|
SortedDict)ÚErrorÚOutcomeÚValueÚcaptureé )Ú
|
EntryQueueÚ TrioToken)ÚTrioInternalErrorÚRunFinishedErrorÚ Cancelled)Ú LOCALS_KEY_KI_PROTECTION_ENABLEDÚ KIManagerÚenable_ki_protection)Ú
|
MultiErrorÚ concat_tb)ÚAbortÚwait_task_rescheduledÚcancel_shielded_checkpointÚCancelShieldedCheckpointÚ PermanentlyDetachCoroutineObjectÚWaitTaskRescheduled)ÚAsyncGenerators)Ústart_thread_soon)Ú Instrumentsé )Ú_core)ÚFinalÚNoPublicConstructorÚcoroutine_or_error)é é )ÚBaseExceptionGroupiè c C s | S ©N© )Úfnr/ r/ úFd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\trio/_core/_run.pyÚ_public8 s r2 Fc
|
C sz dd } t }z| | ¡ W nX tk
|
rt } z:|j}|j}d}|jjjdkr\|j}|d7 }q>| W Y ¢S d }~X Y nX d S )Nc S s dd d S )Nr r r/ r/ r/ r/ r1 Ú function_with_unique_name_xyzzyH s zE_count_context_run_tb_frames.<locals>.function_with_unique_name_xyzzyr r3 r )r ÚrunÚZeroDivisionErrorÚ __traceback__Útb_nextÚtb_frameÚf_codeÚco_name)r3 ÚctxÚexcÚtbÚcountr/ r/ r1 Ú _count_context_run_tb_framesG s
|
r? T)ÚfrozenÚslotsc @ s4 e Zd Zejdd dZdd Zdd Zdd Zd
|
S ) Ú SystemClockc C s t dd¡S )Ni' i@ )Ú_rÚuniformr/ r/ r/ r1 Ú<lambda>a ó zSystemClock.<lambda>©Úfactoryc C s d S r. r/ ©Úselfr/ r/ r1 Ú start_clockc s zSystemClock.start_clockc C s | j t S r. )Úoffsetr rI r/ r/ r1 Ú current_timei s zSystemClock.current_timec C s || ¡ S r. )rM )rJ Údeadliner/ r/ r1 Údeadline_to_sleep_timel s z"SystemClock.deadline_to_sleep_timeN) Ú__name__Ú
|
__module__Ú __qualname__ÚattrÚibrL rK rM rO r/ r/ r/ r1 rB \ s rB c @ s e Zd ZdZdZdS )ÚIdlePrimedTypesr r& N)rP rQ rR ÚWAITING_FOR_IDLEÚAUTOJUMP_CLOCKr/ r/ r/ r1 rU p s rU c C s t | j}d}t|D ].\}}t|trt|}||k rd}|||< qt|dkrt| tr| jrt | j
|
|d j
|
|d _
|
|d S |r| |¡S | S dS )z`Recursively collapse any single-exception groups into that single contained
|
exception.
|
|
FTr r N) ÚlistÚ
|
exceptionsÚ enumerateÚ
|
isinstancer- Úcollapse_exception_groupÚlenr Zcollapser r6 Zderive)ZexcgrouprY ÚmodifiedÚir< Únew_excr/ r/ r1 r\ z s"
|
|
|
ÿ
|
|
r\ )ÚeqrA c @ sP e Zd ZdZejedZejddZdd Z dd Z
|
d d
|
Z d d Z d d Z dS )Ú DeadlineszA container of deadlined cancel scopes.
|
|
Only contains scopes with non-infinite deadlines that are currently
|
attached to at least one task.
|
|
rG r ©Údefaultc C s( t | j|t||f | jd7 _d S ©Nr )r Ú_heapÚidÚ_active©rJ rN Ú cancel_scoper/ r/ r1 Úadd¡ s z Deadlines.addc C s | j d8 _ d S re )rh ri r/ r/ r1 Úremove¥ s zDeadlines.removec C s4 | j r0| j d \}}}||jkr$|S t| j q tS )Nr )rf Ú_registered_deadliner r )rJ rN Ú_rj r/ r/ r1 Ú next_deadline¨ s
|
zDeadlines.next_deadlinec C sn t }g }| jD ]8\}}}||jkr||kr.q| |¡ | |||f¡ qt|| jks\tt| || _d S r. ) Úsetrf rm rk Úappendr] rh ÚAssertionErrorr
|
)rJ ÚseenZ pruned_heaprN Z
|
tiebreakerrj r/ r/ r1 Ú_prune² s
|
|
zDeadlines._prunec C sh d}| j rD| j d d |krDt| j \}}}||jkrd}| ¡ qt| j | jd t krd| ¡ |S )NFr Tr& )rf r rm Úcancelr] rh Ú!DEADLINE_HEAP_MIN_PRUNE_THRESHOLDrt )rJ ÚnowZ did_somethingrN rn rj r/ r/ r1 ÚexpireÇ s
|
|
zDeadlines.expireN)rP rQ rR Ú__doc__rS rT rX rf rh rk rl ro rt rx r/ r/ r/ r1 rb s
|
rb c @ sÐ e Zd ZdZe ¡ ZejddZejdddZeje dddZ
|
eje dddZ ejddddZ dd Z ed
|
d Zejd d Zed d Zedd Zdd Zdd Zedd Zdd Zdd Zdd ZdS ) Ú CancelStatusav Tracks the cancellation status for a contiguous extent
|
of code that will become cancelled, or not, as a unit.
|
|
Each task has at all times a single "active" CancelStatus whose
|
cancellation state determines whether checkpoints executed in that
|
task raise Cancelled. Each 'with CancelScope(...)' context is
|
associated with a particular CancelStatus. When a task enters
|
such a context, a CancelStatus is created which becomes the active
|
CancelStatus for that task; when the 'with' block is exited, the
|
active CancelStatus for that task goes back to whatever it was
|
before.
|
|
CancelStatus objects are arranged in a tree whose structure
|
mirrors the lexical nesting of the cancel scope contexts. When a
|
CancelStatus becomes cancelled, it notifies all of its direct
|
children, who become cancelled in turn (and continue propagating
|
the cancellation down the tree) unless they are shielded. (There
|
will be at most one such child except in the case of a
|
CancelStatus that immediately encloses a nursery.) At the leaves
|
of this tree are the tasks themselves, which get woken up to deliver
|
an abort when their direct parent CancelStatus becomes cancelled.
|
|
You can think of CancelStatus as being responsible for the
|
"plumbing" of cancellations as oppposed to CancelScope which is
|
responsible for the origination of them.
|
|
Frc N©rd Úrepr)rH Úinitr| )rd r} r| c C s$ | j d k r | j j | ¡ | ¡ d S r. )Ú_parentÚ _childrenrk Ú recalculaterI r/ r/ r1 Ú__attrs_post_init__ s
|
z CancelStatus.__attrs_post_init__c C s | j S r. )r~ rI r/ r/ r1 Úparent" s zCancelStatus.parentc C sB | j d k r| j j | ¡ || _ | j d k r>| j j | ¡ | ¡ d S r. )r~ r rl rk r )rJ r r/ r/ r1 r & s
|
|
c C s
|
t | jS r. ©Ú frozensetr rI r/ r/ r1 Úchildren/ s zCancelStatus.childrenc C s
|
t | jS r. )r Ú_tasksrI r/ r/ r1 Útasks3 s zCancelStatus.tasksc C s |dk r || krdS |j }q dS )z
Returns true if this cancel status is a direct or indirect
|
parent of cancel status *other*, or if *other* is *self*.
|
NTF)r )rJ Úotherr/ r/ r1 Úencloses7 s
|
zCancelStatus.enclosesc C sL d | _ | js| jrH| ¡ d| _| jD ] }| ¡ q&| jD ] }| ¡ q:d S ©NT)r r r Ú_mark_abandonedÚeffectively_cancelledÚ'_attempt_delivery_of_any_pending_cancelr )rJ ÚtaskÚchildr/ r/ r1 ÚcloseA s
|
|
|
zCancelStatus.closec C s | j d k o| jj o| j jS r. )r~ Ú_scopeÚshieldr rI r/ r/ r1 Ú$parent_cancellation_is_visible_to_us] s
|
|
ÿýz1CancelStatus.parent_cancellation_is_visible_to_usc C sZ | g}|rV| ¡ }|jjp |j}||jkr||_|rH|jD ] }| ¡ q:| |j¡ qd S r. ) Úpopr Ú cancel_calledr r r r Úextendr )rJ ÚtodoÚcurrentZ new_stater r/ r/ r1 r e s þ
|
|
|
zCancelStatus.recalculatec C s d| _ | jD ] }| ¡ q d S r )Úabandoned_by_misnestingr r )rJ r r/ r/ r1 r x s
|
z CancelStatus._mark_abandonedc C s: | j r t S | jd ks | jjr&| jjS t| jj| j ¡ S r. )r r r~ r r rN ÚminÚeffective_deadlinerI r/ r/ r1 r } s
|
z CancelStatus.effective_deadline)rP rQ rR ry rS rT r r r~ rp r r r r Úpropertyr Úsetterr
r r r r r r r r/ r/ r/ r1 rz Ø s.
|
|
|
|
|
|
|
rz a
|
This is probably a bug in your code, that has caused Trio's internal state to
|
become corrupted. We'll do our best to recover, but from now on there are
|
no guarantees.
|
|
Typically this is caused by one of the following:
|
- yielding within a generator or async generator that's opened a cancel
|
scope or nursery (unless the generator is a @contextmanager or
|
@asynccontextmanager); see https://github.com/python-trio/trio/issues/638
|
- manually calling __enter__ or __exit__ on a trio.CancelScope, or
|
__aenter__ or __aexit__ on the object returned by trio.open_nursery();
|
doing so correctly is difficult and you should use @[async]contextmanager
|
instead, or maybe [Async]ExitStack
|
- using [Async]ExitStack to interleave the entries/exits of cancel scopes
|
and/or nurseries in a way that couldn't be achieved by some nesting of
|
'with' and 'async with' blocks
|
- using the low-level coroutine object protocol to execute some parts of
|
an async function in a different cancel scope/nursery context than
|
other parts
|
If you don't believe you're doing any of these things, please file a bug:
|
https://github.com/python-trio/trio/issues/new
|
)ra r| rA c @ sö e Zd ZdZejdddZejdddZejeddZ ejdddZ
|
ejdddZ ejeddZ ejdddZ edd Zd d
|
Zd d Zd d Zeedd Zedd Zejdd Zedd Zejedd Zedd Zedd ZdS )Ú CancelScopea A *cancellation scope*: the link between a unit of cancellable
|
work and Trio's cancellation system.
|
|
A :class:`CancelScope` becomes associated with some cancellable work
|
when it is used as a context manager surrounding that work::
|
|
cancel_scope = trio.CancelScope()
|
...
|
with cancel_scope:
|
await long_running_operation()
|
|
Inside the ``with`` block, a cancellation of ``cancel_scope`` (via
|
a call to its :meth:`cancel` method or via the expiry of its
|
:attr:`deadline`) will immediately interrupt the
|
``long_running_operation()`` by raising :exc:`Cancelled` at its
|
next :ref:`checkpoint <checkpoints>`.
|
|
The context manager ``__enter__`` returns the :class:`CancelScope`
|
object itself, so you can also write ``with trio.CancelScope() as
|
cancel_scope:``.
|
|
If a cancel scope becomes cancelled before entering its ``with`` block,
|
the :exc:`Cancelled` exception will be raised at the first
|
checkpoint inside the ``with`` block. This allows a
|
:class:`CancelScope` to be created in one :ref:`task <tasks>` and
|
passed to another, so that the first task can later cancel some work
|
inside the second.
|
|
Cancel scopes are not reusable or reentrant; that is, each cancel
|
scope can be used for at most one ``with`` block. (You'll get a
|
:exc:`RuntimeError` if you violate this rule.)
|
|
The :class:`CancelScope` constructor takes initial values for the
|
cancel scope's :attr:`deadline` and :attr:`shield` attributes; these
|
may be freely modified after construction, whether or not the scope
|
has been entered yet, and changes take immediate effect.
|
NF)rd r} T)rd Zkw_onlyc C sd t ¡ }| jrtdd| _t | jkr0| ¡ | ¡ " t| |j d| _ |
|
| j ¡ W 5 Q R X | S )Nz;Each CancelScope may only be used for a single 'with' blockT)Zscoper ) r' Ú current_taskÚ_has_been_enteredÚ RuntimeErrorrM Ú _deadlineru Ú!_might_change_registered_deadlinerz Ú_cancel_statusÚ_activate_cancel_status)rJ r r/ r/ r1 Ú __enter__Ï s ÿ
|
zCancelScope.__enter__c C s8 | j d kr"td | ¡}||_|S t }|j | j k r| j jr>q¨| j |j ¡shtd | |t¡}||_|S td | ||j jt¡}||_|}| | j j
|
¡ n| | j j
|
¡ |d k r| j j r| j j st |trÜd| _d }n4t |tr| t¡\}}|rd| _|rt|}| j ¡ | ¡ d | _ W 5 Q R X |S )NzRCancel scope stack corrupted: attempted to exit {!r} which had already been exitedzKCancel scope stack corrupted: attempted to exit {!r} from unrelated {!r}
|
{}zbCancel scope stack corrupted: attempted to exit {!r} in {!r} that's still within its child {!r}
|
{}T)r¤ r¡ ÚformatÚ __context__r r r ÚMISNESTING_ADVICEr r¥ r r r r[ r Úcancelled_caughtr- Úsplitr\ r r£ )rJ r< r` Z
|
scope_taskÚmatchedr/ r/ r1 Ú_closeÞ sj
|
ÿÿ þÿûÿ ÿþý
|
|
|
zCancelScope._closec C sp dt t< | |¡}|d kr dS ||kr,dS |j}z|W 5 t ¡ \}}}||ksVt||_~~~~t X d S ©NTF)Úlocalsr r r¨ ÚsysÚexc_inforr )rJ Úetyper< r= Z"remaining_error_after_cancel_scopeÚ old_contextrn Úvaluer/ r/ r1 Ú__exit__' s
|
|
zCancelScope.__exit__c C s | j d k rd}n| jr d}nd}| jr,d}nX| jtkr<d}nHz
|
t }W n tk
|
r^ d}Y n&X d t| j| | j|kr~dnd¡}d t | ||¡S )
|
NÚactiveZexitedÚunboundz , cancelledÚ z , deadline is {:.2f} seconds {}zfrom nowZagoz!<trio.CancelScope at {:#x}, {}{}>)
|
r¤ r Ú_cancel_calledr¢ r rM r¡ r§ Úabsrg )rJ ZbindingÚstaterw r/ r/ r1 Ú__repr__I s$
|
|
|
|
þzCancelScope.__repr__c
|
c s¤ z
|
d V W 5 | j }| jd ks"| jr(t}n| j}||kr|| _ tj}|jrR|j ¡ }|tkrh|j
|
|| ¡ |tkr~|j || ¡ |jr|j ¡ }||kr| ¡ X d S r. ) rm r¤ r¹ r r¢ ÚGLOBAL_RUN_CONTEXTÚrunnerÚis_guestÚ deadlinesro rl rk Úforce_guest_tick_asap)rJ ÚoldÚnewr¾ Zold_next_deadlineZnew_next_deadliner/ r/ r1 r£ b s&
|
|
|
z-CancelScope._might_change_registered_deadlinec C s | j S )a4 Read-write, :class:`float`. An absolute time on the current
|
run's clock at which this scope will automatically become
|
cancelled. You can adjust the deadline by modifying this
|
attribute, e.g.::
|
|
# I need a little more time!
|
cancel_scope.deadline += 30
|
|
Note that for efficiency, the core run loop only checks for
|
expired deadlines every once in a while. This means that in
|
certain cases there may be a short delay between when the clock
|
says the deadline should have expired, and when checkpoints
|
start raising :exc:`~trio.Cancelled`. This is a very obscure
|
corner case that you're unlikely to notice, but we document it
|
for completeness. (If this *does* cause problems for you, of
|
course, then `we want to know!
|
<https://github.com/python-trio/trio/issues>`__)
|
|
Defaults to :data:`math.inf`, which means "no deadline", though
|
this can be overridden by the ``deadline=`` argument to
|
the :class:`~trio.CancelScope` constructor.
|
)r¢ rI r/ r/ r1 rN { s zCancelScope.deadlinec C s" | ¡ t|| _W 5 Q R X d S r. )r£ Úfloatr¢ )rJ Z new_deadliner/ r/ r1 rN s
|
c C s | j S )a Read-write, :class:`bool`, default :data:`False`. So long as
|
this is set to :data:`True`, then the code inside this scope
|
will not receive :exc:`~trio.Cancelled` exceptions from scopes
|
that are outside this scope. They can still receive
|
:exc:`~trio.Cancelled` exceptions from (1) this scope, or (2)
|
scopes inside this scope. You can modify this attribute::
|
|
with trio.CancelScope() as cancel_scope:
|
cancel_scope.shield = True
|
# This cannot be interrupted by any means short of
|
# killing the process:
|
await sleep(10)
|
|
cancel_scope.shield = False
|
# Now this can be cancelled normally:
|
await sleep(10)
|
|
Defaults to :data:`False`, though this can be overridden by the
|
``shield=`` argument to the :class:`~trio.CancelScope` constructor.
|
)Ú_shieldrI r/ r/ r1 r s zCancelScope.shieldc C s0 t |tstd|| _| jd k r,| j ¡ d S )Nzshield must be a bool)r[ ÚboolÚ TypeErrorrÅ r¤ r )rJ Ú new_valuer/ r/ r1 r ² s
|
|
|
c C s< | j r
|
dS | ¡ d| _ W 5 Q R X | jdk r8| j ¡ dS )z¥Cancels this scope immediately.
|
|
This method is idempotent, i.e., if the scope was already
|
cancelled then this method silently does nothing.
|
NT)r¹ r£ r¤ r rI r/ r/ r1 ru » s
|
|
zCancelScope.cancelc C s0 | j dk s| js*| js*t | jkr*| ¡ | jS )a! Readonly :class:`bool`. Records whether cancellation has been
|
requested for this scope, either by an explicit call to
|
:meth:`cancel` or by the deadline expiring.
|
|
This attribute being True does *not* necessarily mean that the
|
code within the scope has been, or will be, affected by the
|
cancellation. For example, if :meth:`cancel` was called after
|
the last checkpoint in the ``with`` block, when it's too late to
|
deliver a :exc:`~trio.Cancelled` exception, then this attribute
|
will still be True.
|
|
This attribute is mostly useful for debugging and introspection.
|
If you want to know whether or not a chunk of code was actually
|
cancelled, then :attr:`cancelled_caught` is usually more
|
appropriate.
|
N)r¤ r r¹ rM r¢ ru rI r/ r/ r1 r É s zCancelScope.cancel_called)rP rQ rR ry rS rT r¤ r r rm r¹ rª r¢ rÅ r r¦ r rµ r¼ r r£ r rN r r ru r r/ r/ r/ r1 r s: &
|
I"
|
|
|
|
r )Ú metaclass)ra Úhashr| c @ sF e Zd Ze ¡ Ze ¡ ZejddZejddZdd Z dddZ
|
dS ) Ú _TaskStatusFrc Nc C s d t| ¡S )Nz <Task status object at {:#x}>)r§ rg rI r/ r/ r1 r¼ õ s z_TaskStatus.__repr__c C sü | j rtdd| _ || _| jjjr(d S | jjr4t| jj }t
|
| j_ |D ] }| j|_ d |_ | jj |¡ qJ| jjj}t
|
| jjj}| | jj¡ |D ]
|
}d |_q|D ]}| d ¡ q¦|D ]}| jj|_qº|D ]}| | jj¡ qÎ| jj rît| j ¡ d S )Nz.called 'started' twice on the same task statusT)Ú_called_startedr¡ Ú_valueÚ _old_nurseryr¤ r Ú _new_nurseryÚ_closedrr r rp Ú_parent_nurseryÚ_eventual_parent_nurseryrk r
r ÚdiscardÚ _parent_taskr r¥ Ú_check_nursery_closed)rJ r´ r r Zcancel_status_childrenZcancel_status_tasksÚ cancel_statusr/ r/ r1 Ústartedø s4
|
|
|
|
z_TaskStatus.started)N) rP rQ rR rS rT rÎ rÏ rÌ rÍ r¼ r× r/ r/ r/ r1 rË î s rË c @ sD e Zd ZdZejddZedd Zedd Z dd Z
|
d
|
d Z d S ) ÚNurseryManagera Nursery context manager.
|
|
Note we explicitly avoid @asynccontextmanager and @async_generator
|
since they add a lot of extraneous stack frames to exceptions, as
|
well as cause problematic behavior with handling of StopIteration
|
and StopAsyncIteration.
|
|
Frc c à s. t | _| j ¡ t t | j| j¡| _| jS r. )r r r¦ ÚNurseryÚ_creater Ústrict_exception_groupsÚ_nurseryrI r/ r/ r1 Ú
|
__aenter__: s
|
ÿzNurseryManager.__aenter__c à st | j |¡I d H }| j |¡}|d kr*dS ||kr6dS |j}z|W 5 t ¡ \}}}||ks`t||_~~~~X d S r® )rÜ Ú_nested_child_finishedr r r¨ r° r± rr ) rJ r² r< r= r` Zcombined_error_from_nurseryr³ rn r´ r/ r/ r1 Ú __aexit__C s zNurseryManager.__aexit__c C s t dd S )Nz@use 'async with open_nursery(...)', not 'with open_nursery(...)')r¡ rI r/ r/ r1 r¦ [ s ÿzNurseryManager.__enter__c C s ds t dd S )NFz#Never called, but should be defined)rr rI r/ r/ r1 rµ ` s zNurseryManager.__exit__N) rP rQ rR ry rS rT rÛ r rÝ rß r¦ rµ r/ r/ r/ r1 rØ - s
|
|
rØ c C s | dkrt jj} t| dS )a° Returns an async context manager which must be used to create a
|
new `Nursery`.
|
|
It does not block on entry; on exit it blocks until all child tasks
|
have exited.
|
|
Args:
|
strict_exception_groups (bool): If true, even a single raised exception will be
|
wrapped in an exception group. This will eventually become the default
|
behavior. If not specified, uses the value passed to :func:`run`.
|
|
N©rÛ )r½ r¾ rÛ rØ rà r/ r/ r1 Ú open_nurseryd s rá c @ st e Zd ZdZdd Zedd Zedd Zdd Zd
|
d Z d d Z
|
dd Z ddddZ ddddZ dd ZdS )rÙ at A context which may be used to spawn (or cancel) child tasks.
|
|
Not constructed directly, use `open_nursery` instead.
|
|
The nursery will remain open until all child tasks have completed,
|
or until it is cancelled, at which point it will cancel all its
|
remaining child tasks and close.
|
|
Nurseries ensure the absence of orphaned Tasks, since all running
|
tasks will belong to an open Nursery.
|
|
Attributes:
|
cancel_scope:
|
Creating a nursery also implicitly creates a cancellation scope,
|
which is exposed as the :attr:`cancel_scope` attribute. This is
|
used internally to implement the logic where if an error occurs
|
then ``__aexit__`` cancels all children, but you can use it for
|
other things, e.g. if you want to explicitly cancel all children
|
in response to some external event.
|
c C sb || _ || _|j | ¡ |j| _|| _| jj| jks8tt | _g | _ d| _
|
d| _ d| _ d| _ d S )NTFr )rÔ Ú_strict_exception_groupsÚ_child_nurseriesrq r¤ rj rr rp r Ú _pending_excsÚ_nested_child_runningÚ_parent_waiting_in_aexitÚ_pending_startsrÐ )rJ Ú parent_taskrj rÛ r/ r/ r1 Ú__init__ s zNursery.__init__c C s
|
t | jS )zk(`frozenset`): Contains all the child :class:`~trio.lowlevel.Task`
|
objects which are still running.r rI r/ r/ r1 Ú child_tasks¢ s zNursery.child_tasksc C s | j S )z<(`~trio.lowlevel.Task`): The Task that opened this nursery.)rÔ rI r/ r/ r1 rè ¨ s zNursery.parent_taskc C s | j |¡ | j ¡ d S r. )rä rq rj ru )rJ r< r/ r/ r1 Ú_add_exc s zNursery._add_excc C s8 t | j| j| jgs4d| _| jr4d| _tj | j ¡ d S r® )
|
Úanyrå r rç rÐ ræ r½ r¾ Ú
|
reschedulerÔ rI r/ r/ r1 rÕ ± s
|
z Nursery._check_nursery_closedc C s. | j |¡ t|tr"| |j¡ | ¡ d S r. )r rl r[ r rë ÚerrorrÕ )rJ r Úoutcomer/ r/ r1 Ú_child_finished¸ s
|
zNursery._child_finishedc
|
sÆ |d k r |¡ d _ ¡ jsH fdd}d _t|I d H n>zt I d H W n, tk
|
r } z |¡ W 5 d }~X Y nX jj
|
¡ }| kst j rÂzt j j dW ¢S ` X d S )NFc s t| j¡ tjS r. )rë r rî r ZFAILED)Ú raise_cancelrI r/ r1 ÚabortedÊ s z/Nursery._nested_child_finished.<locals>.abortedT)Z _collapse)rë rå rÕ rÐ ræ r Ú
|
checkpointÚ BaseExceptionrÔ rã r rr rä r râ )rJ Znested_child_excrò r< Úpoppedr/ rI r1 rÞ ¾ s*
|
ÿ
|
z Nursery._nested_child_finishedN)Únamec G s t j ||| |¡ dS )uV Creates a child task, scheduling ``await async_fn(*args)``.
|
|
This and :meth:`start` are the two fundamental methods for
|
creating concurrent tasks in Trio.
|
|
Note that this is *not* an async function and you don't use await
|
when calling it. It sets up the new task, but then returns
|
immediately, *before* it has a chance to run. The new task wonât
|
actually get a chance to do anything until some later point when
|
you execute a checkpoint and the scheduler decides to run it.
|
If you want to run a function and immediately wait for its result,
|
then you don't need a nursery; just use ``await async_fn(*args)``.
|
If you want to wait for the task to initialize itself before
|
continuing, see :meth:`start`.
|
|
It's possible to pass a nursery object into another task, which
|
allows that task to start new child tasks in the first task's
|
nursery.
|
|
The child task inherits its parent nursery's cancel scopes.
|
|
Args:
|
async_fn: An async callable.
|
args: Positional arguments for ``async_fn``. If you want
|
to pass keyword arguments, use
|
:func:`functools.partial`.
|
name: The name for this task. Only used for
|
debugging/introspection
|
(e.g. ``repr(task_obj)``). If this isn't a string,
|
:meth:`start_soon` will try to make it one. A
|
common use case is if you're wrapping a function
|
before spawning a new task, you might pass the
|
original function as the ``name=`` to make
|
debugging easier.
|
|
Raises:
|
RuntimeError: If this nursery is no longer open
|
(i.e. its ``async with`` block has
|
exited).
|
N)r½ r¾ Ú
|
spawn_impl)rJ Úasync_fnrö Úargsr/ r/ r1 Ú
|
start_soonå s )zNursery.start_soonc
|
Ç s¢ | j rtdzv| jd7 _t 4 I dH 6}t|| }tj||d}tj
|
||||¡}| |_ W 5 Q I dH R X |j s|td|j W ¢S | jd8 _| ¡ X dS )aö Creates and initializes a child task.
|
|
Like :meth:`start_soon`, but blocks until the new task has
|
finished initializing itself, and optionally returns some
|
information from it.
|
|
The ``async_fn`` must accept a ``task_status`` keyword argument,
|
and it must make sure that it (or someone) eventually calls
|
``task_status.started()``.
|
|
The conventional way to define ``async_fn`` is like::
|
|
async def async_fn(arg1, arg2, *, task_status=trio.TASK_STATUS_IGNORED):
|
...
|
task_status.started()
|
...
|
|
:attr:`trio.TASK_STATUS_IGNORED` is a special global object with
|
a do-nothing ``started`` method. This way your function supports
|
being called either like ``await nursery.start(async_fn, arg1,
|
arg2)`` or directly like ``await async_fn(arg1, arg2)``, and
|
either way it can call ``task_status.started()`` without
|
worrying about which mode it's in. Defining your function like
|
this will make it obvious to readers that it supports being used
|
in both modes.
|
|
Before the child calls ``task_status.started()``, it's
|
effectively run underneath the call to :meth:`start`: if it
|
raises an exception then that exception is reported by
|
:meth:`start`, and does *not* propagate out of the nursery. If
|
:meth:`start` is cancelled, then the child task is also
|
cancelled.
|
|
When the child calls ``task_status.started()``, it's moved out
|
from underneath :meth:`start` and into the given nursery.
|
|
If the child task passes a value to
|
``task_status.started(value)``, then :meth:`start` returns this
|
value. Otherwise it returns ``None``.
|
ú!Nursery is closed to new arrivalsr N)Ú task_statusz2child exited without calling task_status.started())rÐ r¡ rç rÕ rá rË Ú functoolsÚpartialr½ r¾ r÷ rÒ rÌ rÍ )rJ rø rö rù Z old_nurseryrü Zthunkr r/ r/ r1 Ústart s& )
|
ÿ
|
z Nursery.startc C s | j r
|
td S r. )r rr rI r/ r/ r1 Ú__del__P s zNursery.__del__)rP rQ rR ry ré r rê rè rë rÕ rð rÞ rú rÿ r r/ r/ r/ r1 rÙ w s
|
|
'+@rÙ )ra rÊ r| rA c @ s e Zd Ze ¡ Ze ¡ Ze ¡ Ze ¡ Ze ¡ Z ejde
|
¡ j dZ ejddZejddZejddZejddZejedZejddZejddZejddZdd Zed d
|
Zed d Zed d ZejdddZ dd Z dd Z dd Z dd Z dS )ÚTaskF)r} rH Nrc rG r c C s d | jt| ¡S )Nz<Task {!r} at {:#x}>)r§ rö rg rI r/ r/ r1 r¼ } s z Task.__repr__c C s | j S )z²The nursery this task is inside (or None if this is the "init"
|
task).
|
|
Example use case: drawing a visualization of the task tree in a
|
debugger.
|
|
)rÑ rI r/ r/ r1 Úparent_nursery s zTask.parent_nurseryc C s | j S )a The nursery this task will be inside after it calls
|
``task_status.started()``.
|
|
If this task has already called ``started()``, or if it was not
|
spawned using `nursery.start() <trio.Nursery.start>`, then
|
its `eventual_parent_nursery` is ``None``.
|
|
)rÒ rI r/ r/ r1 Úeventual_parent_nursery s
|
z Task.eventual_parent_nurseryc C s
|
t | jS )zqThe nurseries this task contains.
|
|
This is a list, with outer nurseries before inner nurseries.
|
|
)rX rã rI r/ r/ r1 Úchild_nurseries s zTask.child_nurseriesr{ c C sJ | j d k r| j j | ¡ || _ | j d k rF| j j | ¡ | j jrF| ¡ d S r. )r¤ r rl rk r r )rJ rÖ r/ r/ r1 r¥ ¨ s
|
|
z Task._activate_cancel_statusc C sD | |¡}t|tk r tdd | _ |tjkr@| j | t|¡ d S )Nz%abort function must return Abort enum)Ú _abort_funcÚtyper r Ú SUCCEEDEDÚ_runnerrí r )rJ rñ Úsuccessr/ r/ r1 Ú_attempt_abort± s
|
|
zTask._attempt_abortc C s0 | j d krd S | jjsd S dd }| |¡ d S )Nc S s t ¡ d S r. )r rÚ r/ r/ r/ r1 rñ Å s zBTask._attempt_delivery_of_any_pending_cancel.<locals>.raise_cancel)r r¤ r r
|
©rJ rñ r/ r/ r1 r ¿ s
|
z,Task._attempt_delivery_of_any_pending_cancelc s4 j js t jd krd S fdd} |¡ d S )Nc s d j _td S )NF)r Ú
|
ki_pendingÚKeyboardInterruptr/ rI r/ r1 rñ Ï s z:Task._attempt_delivery_of_pending_ki.<locals>.raise_cancel)r r rr r r
|
r r/ rI r1 Ú _attempt_delivery_of_pending_kiÊ s
|
|
z$Task._attempt_delivery_of_pending_ki)!rP rQ rR rS rT rÑ Úcoror rö ÚcontextÚ itertoolsr> Ú__next__Ú_counterÚ _next_send_fnÚ
|
_next_sendr Úcustom_sleep_datarX rã rÒ Ú_cancel_pointsÚ_schedule_pointsr¼ r r r r r¤ r¥ r
|
r r r/ r/ r/ r1 r Y s4
|
|
|
|
r c @ s e Zd ZU ded< eed< dS )Ú
|
RunContextÚRunnerr¾ r N)rP rQ rR Ú__annotations__r r/ r/ r/ r1 r Û s
|
r )r@ c @ s4 e Zd Ze ¡ Ze ¡ Ze ¡ Ze ¡ Ze ¡ Z dS )Ú_RunStatisticsN)
|
rP rQ rR rS rT Ú tasks_livingÚtasks_runnableÚseconds_to_next_deadlineÚ io_statisticsÚrun_sync_soon_queue_sizer/ r/ r/ r1 r ã s
|
r )ra rÊ rA c @ sd e Zd ZU e ¡ Ze ¡ Ze ¡ Ze ¡ Ze ¡ Z dd Z
|
e g e f e d< eje
|
edZdd ZdS )Ú
|
GuestStatec C s t d S r. )r r/ r/ r/ r1 rE rF zGuestState.<lambda>Ú_value_factory)rH r c
|
sà z j j¡W nX tk
|
r6 jj¡ Y d S tk
|
rj } z t|¡ W Y ¢d S d }~X Y nX t jj
|
j d}dkst |ts|j r°| _ d j_ j¡ n,d j_ fdd} fdd}t|| d S )Nr TFc s j j ¡S r. )r¾ Ú
|
io_managerÚ
|
get_eventsr/ ©rJ Útimeoutr/ r1 r% s z)GuestState.guest_tick.<locals>.get_eventsc s fdd} |¡ d S )Nc s _ dj_ ¡ d S r )Úunrolled_run_next_sendr¾ Úguest_tick_scheduledÚ
|
guest_tickr/ )Úevents_outcomerJ r/ r1 Úin_main_thread" s z>GuestState.guest_tick.<locals>.deliver.<locals>.in_main_thread)Úrun_sync_soon_threadsafe)r+ r, rI )r+ r1 Údeliver! s z&GuestState.guest_tick.<locals>.deliver)r( ÚsendÚunrolled_run_genÚ StopIterationÚ done_callbackr¾ Úmain_task_outcomer r r r$ r% r[ r´ r) Ú run_sync_soon_not_threadsafer* r$ )rJ r< r+ r% r. r/ r& r1 r* s" zGuestState.guest_tickN)rP rQ rR rS rT r¾ r- r4 r2 r0 r# r r r r r( r* r/ r/ r/ r1 r" ÿ s
|
r" c @ s¸ e Zd ZU e ¡ Ze ¡ Zeed< e ¡ Z e ¡ Z
|
e ¡ Z eje dZ ejedZejedZejedZejddZejddZejddZejddZejddZejedZejddZeje dZ eje dZ ejddZ ejddZ!dd Z"dd Z#e$d
|
d Z%e$d d Z&e$dd Z'e$dd Z(e$e)fddZ*dddddZ+dd Z,e$dddddZ-d d Z.e$d d Z/ejddZ0d d! Z1d"d# Z2eje3dZ4e$d'd%d&Z5dS )(r Ú instrumentsrG Nrc Fc C s | j r
|
d S d| _ | j ¡ d S r )r) r$ Z force_wakeuprI r/ r/ r1 rÁ M s z Runner.force_guest_tick_asapc C sB | j ¡ | j ¡ | j ¡ d| jkr4| j d¡ | j ¡ d S )NZ after_run)r$ r Ú entry_queueÚ asyncgensr5 ÚcallÚ
|
ki_managerrI r/ r/ r1 r S s
|
|
|
|
z Runner.closec C s< | j ¡ | ¡ }tt| jt| j|| j ¡ | j
|
¡ dS )ah Returns an object containing run-loop-level debugging information.
|
|
Currently the following fields are defined:
|
|
* ``tasks_living`` (int): The number of tasks that have been spawned
|
and not yet exited.
|
* ``tasks_runnable`` (int): The number of tasks that are currently
|
queued on the run queue (as opposed to blocked waiting for something
|
to happen).
|
* ``seconds_to_next_deadline`` (float): The time until the next
|
pending cancel scope deadline. May be negative if the deadline has
|
expired but we haven't yet processed cancellations. May be
|
:data:`~math.inf` if there are no pending deadlines.
|
* ``run_sync_soon_queue_size`` (int): The number of
|
unprocessed callbacks queued via
|
:meth:`trio.lowlevel.TrioToken.run_sync_soon`.
|
* ``io_statistics`` (object): Some statistics from Trio's I/O
|
backend. This always has an attribute ``backend`` which is a string
|
naming which operating-system-specific I/O backend is in use; the
|
other attributes vary between backends.
|
|
)r r r r r! ) rÀ ro rM r r] r Úrunqr$ Z
|
statisticsr6 Úsize)rJ r r/ r/ r1 Úcurrent_statistics\ s ûzRunner.current_statisticsc C s
|
| j ¡ S )zÒReturns the current time according to Trio's internal clock.
|
|
Returns:
|
float: The current time.
|
|
Raises:
|
RuntimeError: if not inside a call to :func:`trio.run`.
|
|
)ÚclockrM rI r/ r/ r1 rM } s zRunner.current_timec C s | j S )z-Returns the current :class:`~trio.abc.Clock`.)r= rI r/ r/ r1 Ú current_clock s zRunner.current_clockc C s | j S )z{Returns the current root :class:`Task`.
|
|
This is the task that is the ultimate parent of all other tasks.
|
|
)Ú init_taskrI r/ r/ r1 Úcurrent_root_task s zRunner.current_root_taskc C s |t krtd}|j| ks t|jdks,t|jj|_||_d|_d|_ | j
|
s\| j r\| ¡ | j
|
|¡ d| jkr| j d|¡ dS )aË Reschedule the given task with the given
|
:class:`outcome.Outcome`.
|
|
See :func:`wait_task_rescheduled` for the gory details.
|
|
There must be exactly one call to :func:`reschedule` for every call to
|
:func:`wait_task_rescheduled`. (And when counting, keep in mind that
|
returning :data:`Abort.SUCCEEDED` from an abort callback is equivalent
|
to calling :func:`reschedule` once.)
|
|
Args:
|
task (trio.lowlevel.Task): the task to be rescheduled. Must be blocked
|
in a call to :func:`wait_task_rescheduled`.
|
next_send (outcome.Outcome): the value (or error) to return (or
|
raise) from :func:`wait_task_rescheduled`.
|
|
NZtask_scheduled)Ú_NO_SENDr r rr r r r/ r r r r: r¿ rÁ rq r5 r8 )rJ r Ú next_sendr/ r/ r1 rí s
|
|
zRunner.reschedule©Ú system_taskr c
|
C sH |d k r|j rtd|d kr,| jd ks,tt|f| }|d krF|}t|tjrX|j}t|t szd
|
|j |j ¡}W n t k
|
r t|}Y nX |d kr²|r¬| j ¡ }nt }t|dsÌdd }||}|jj t|¡ tj||| ||d} | j | ¡ |d k r |j | ¡ | |j ¡ d| j kr8| j d| ¡ | | d ¡ | S )Nrû z{}.{}Úcr_framec Ó s
|
| I d H S r. r/ )Z orig_coror/ r/ r1 Úpython_wrapperæ s z)Runner.spawn_impl.<locals>.python_wrapper)r r r¾ rö r Z task_spawned)!rÐ r¡ r? rr r* r[ rý rþ ÚfuncÚstrr§ rQ rR ÚAttributeErrorr| Úsystem_contextÚcopyr ÚhasattrrE Úf_localsÚ
|
setdefaultr r rÚ r rk r r¥ r¤ r5 r8 rí )
|
rJ rø rù Znurseryrö rD r r rF r r/ r/ r1 r÷ ¾ sJ
|
|
ÿ
|
zRunner.spawn_implc
|
C sæ |j d k rp|j jrp|j jd krpztd |t¡W n< tk
|
rn } z t|trV|j|_ t|}W 5 d }~X Y nX |
|
d ¡ | j |¡ || j kr¤| ¡ | j rÊtn&|| jkr¼|| _td }|j ||¡ d| jkrâ| j d|¡ d S )Nz`Cancel scope stack corrupted: cancel scope surrounding {!r} was closed before the task exited
|
{}Ú task_exited)r¤ r r r¡ r§ r© r[ r rî r¨ r¥ r rl r? Úunwrapr Ú main_taskr3 r rÑ rð r5 r8 )rJ r rï r` r/ r/ r1 rO ÿ s: ÿþ
|
ý þÿ
|
|
|
|
|
zRunner.task_exited)rö r c G s" t d¡ | j||| j|d|dS )a» Spawn a "system" task.
|
|
System tasks have a few differences from regular tasks:
|
|
* They don't need an explicit nursery; instead they go into the
|
internal "system nursery".
|
|
* If a system task raises an exception, then it's converted into a
|
:exc:`~trio.TrioInternalError` and *all* tasks are cancelled. If you
|
write a system task, you should be careful to make sure it doesn't
|
crash.
|
|
* System tasks are automatically cancelled when the main task exits.
|
|
* By default, system tasks have :exc:`KeyboardInterrupt` protection
|
*enabled*. If you want your task to be interruptible by control-C,
|
then you need to use :func:`disable_ki_protection` explicitly (and
|
come up with some plan for what to do with a
|
:exc:`KeyboardInterrupt`, given that system tasks aren't allowed to
|
raise exceptions).
|
|
* System tasks do not inherit context variables from their creator.
|
|
Towards the end of a call to :meth:`trio.run`, after the main
|
task and all system tasks have exited, the system nursery
|
becomes closed. At this point, new calls to
|
:func:`spawn_system_task` will raise ``RuntimeError("Nursery
|
is closed to new arrivals")`` instead of creating a system
|
task. It's possible to encounter this state either in
|
a ``finally`` block in an async generator, or in a callback
|
passed to :meth:`TrioToken.run_sync_soon` at the right moment.
|
|
Args:
|
async_fn: An async callable.
|
args: Positional arguments for ``async_fn``. If you want to pass
|
keyword arguments, use :func:`functools.partial`.
|
name: The name for this task. Only used for debugging/introspection
|
(e.g. ``repr(task_obj)``). If this isn't a string,
|
:func:`spawn_system_task` will try to make it one. A common use
|
case is if you're wrapping a function before spawning a new
|
task, you might pass the original function as the ``name=`` to
|
make debugging easier.
|
context: An optional ``contextvars.Context`` object with context variables
|
to use for this task. You would normally get a copy of the current
|
context with ``context = contextvars.copy_context()`` and then you would
|
pass that ``context`` object here.
|
|
Returns:
|
Task: the newly spawned task
|
|
ÚtrioTrC )r rp r÷ Úsystem_nursery)rJ rø rö r rù r/ r/ r1 Úspawn_system_task/ s 5
|
úzRunner.spawn_system_taskc à s" t 4 I d H }t 4 I d H Æ| _t 4 I d H }z| |||d ¡| _W nb tk
|
r¬ } zDt|| _W Y ¢4W 5 Q I d H R £ W 5 Q I d H R £ W 5 Q I d H R £ d S d }~X Y nX | j| jjd|ddd W 5 Q I d H R X | jj
|
¡ W 5 Q I d H R X | j | ¡I d H |j
|
¡ W 5 Q I d H R X d S )Nr/ z <TrioToken.run_sync_soon task>T©rD ) rá rS r÷ rQ rô r r3 r6 r rj ru r7 Zfinalize_remaining)rJ rø rù Zrun_sync_soon_nurseryZmain_task_nurseryr< r/ r/ r1 r} n s. ÿ
|
|
Hû z Runner.initc C s | j dkrt | j¡| _ | j S )z[Retrieve the :class:`TrioToken` for the current call to
|
:func:`trio.run`.
|
|
N)Ú
|
trio_tokenr rÚ r6 rI r/ r/ r1 Úcurrent_trio_token s
|
zRunner.current_trio_tokenc C s2 d| _ z| j | j¡ W n tk
|
r, Y nX d S r )r r6 Z run_sync_soonÚ_deliver_ki_cbr rI r/ r/ r1 Ú
|
deliver_kiª s
|
zRunner.deliver_kic C s4 | j s
|
d S | jd k st| jd k r&d S | j ¡ d S r. )r rQ rr r3 r rI r/ r/ r1 rX ± s
|
zRunner._deliver_ki_cbç c s< t }|t|f |j < fdd}t|I dH dS )a¬
|
Block until there are no runnable tasks.
|
|
This is useful in testing code when you want to give other tasks a
|
chance to "settle down". The calling task is blocked, and doesn't wake
|
up until all other tasks are also blocked for at least ``cushion``
|
seconds. (Setting a non-zero ``cushion`` is intended to handle cases
|
like two tasks talking to each other over a local socket, where we
|
want to ignore the potential brief moment between a send and receive
|
when all tasks are blocked.)
|
|
Note that ``cushion`` is measured in *real* time, not the Trio clock
|
time.
|
|
If there are multiple tasks blocked in :func:`wait_all_tasks_blocked`,
|
then the one with the shortest ``cushion`` is the one woken (and
|
this task becoming unblocked resets the timers for the remaining
|
tasks). If there are multiple tasks that have exactly the same
|
``cushion``, then all are woken.
|
|
You should also consider :class:`trio.testing.Sequencer`, which
|
provides a more explicit way to control execution ordering within a
|
test, and will often produce more readable tests.
|
|
Example:
|
Here's an example of one way to test that Trio's locks are fair: we
|
take the lock in the parent, start a child, wait for the child to be
|
blocked waiting for the lock (!), and then check that we can't
|
release and immediately re-acquire the lock::
|
|
async def lock_taker(lock):
|
await lock.acquire()
|
lock.release()
|
|
async def test_lock_fairness():
|
lock = trio.Lock()
|
await lock.acquire()
|
async with trio.open_nursery() as nursery:
|
nursery.start_soon(lock_taker, lock)
|
# child hasn't run yet, we have the lock
|
assert lock.locked()
|
assert lock._owner is trio.lowlevel.current_task()
|
await trio.testing.wait_all_tasks_blocked()
|
# now the child has run and is blocked on lock.acquire(), we
|
# still have the lock
|
assert lock.locked()
|
assert lock._owner is trio.lowlevel.current_task()
|
lock.release()
|
try:
|
# The child has a prior claim, so we can't have it
|
lock.acquire_nowait()
|
except trio.WouldBlock:
|
assert lock._owner is not trio.lowlevel.current_task()
|
print("PASS")
|
else:
|
print("FAIL")
|
|
c s j = tjS r. )Úwaiting_for_idler r ©rn ©ÚkeyrJ r/ r1 Úabort s z,Runner.wait_all_tasks_blocked.<locals>.abortN)r rg r[ r )rJ Úcushionr r_ r/ r] r1 Úwait_all_tasks_blockedÄ s
|
;
|
z Runner.wait_all_tasks_blocked)rZ )6rP rQ rR rS rT r= r5 r% r r$ r9 rÛ ÚdictZ_localsr r: rp r rb rÀ r? rS rJ rQ r3 r r6 rV r# r7 r Úclock_autojump_thresholdr¿ r) rÁ r r2 r< rM r> r@ rA rí r÷ rO rT r} rW r rY rX r r[ ra r/ r/ r/ r1 r , s^
|
|
|
|
|
" ÿ A0>%
|
r c C s t tdrtd| dkr t } t|}t }t }| tj d¡ t
|
}t | |||||d}|j |¡ | |j|¡ |t_|S )z@Create a Runner object and install it as the GLOBAL_RUN_CONTEXT.r¾ z+Attempted to call run() from inside a run()NrR )r= r5 r$ rJ r9 rÛ )rL r½ r¡ rB r% Ú TheIOManagerr r4 r rp r r r7 Z install_hooksÚinstallrY r¾ )r= r5 Ú*restrict_keyboard_interrupt_to_checkpointsrÛ r$ rJ r9 r¾ r/ r/ r1 Ú setup_runnerM s*
|
|
ú rg r/ )r= r5 rf rÛ c G sx d}t ||||}t|| |}d} z| | ¡}
|
W n tk
|
rH Y qXY nX |j |
|
¡} q"t|jtrl|jj S |jj
|
dS )aj Run a Trio-flavored async function, and return the result.
|
|
Calling::
|
|
run(async_fn, *args)
|
|
is the equivalent of::
|
|
await async_fn(*args)
|
|
except that :func:`run` can (and must) be called from a synchronous
|
context.
|
|
This is Trio's main entry point. Almost every other function in Trio
|
requires that you be inside a call to :func:`run`.
|
|
Args:
|
async_fn: An async function.
|
|
args: Positional arguments to be passed to *async_fn*. If you need to
|
pass keyword arguments, then use :func:`functools.partial`.
|
|
clock: ``None`` to use the default system-specific monotonic clock;
|
otherwise, an object implementing the :class:`trio.abc.Clock`
|
interface, like (for example) a :class:`trio.testing.MockClock`
|
instance.
|
|
instruments (list of :class:`trio.abc.Instrument` objects): Any
|
instrumentation you want to apply to this run. This can also be
|
modified during the run; see :ref:`instrumentation`.
|
|
restrict_keyboard_interrupt_to_checkpoints (bool): What happens if the
|
user hits control-C while :func:`run` is running? If this argument
|
is False (the default), then you get the standard Python behavior: a
|
:exc:`KeyboardInterrupt` exception will immediately interrupt
|
whatever task is running (or if no task is running, then Trio will
|
wake up a task to be interrupted). Alternatively, if you set this
|
argument to True, then :exc:`KeyboardInterrupt` delivery will be
|
delayed: it will be *only* be raised at :ref:`checkpoints
|
<checkpoints>`, like a :exc:`Cancelled` exception.
|
|
The default behavior is nice because it means that even if you
|
accidentally write an infinite loop that never executes any
|
checkpoints, then you can still break out of it using control-C.
|
The alternative behavior is nice if you're paranoid about a
|
:exc:`KeyboardInterrupt` at just the wrong place leaving your
|
program in an inconsistent state, because it means that you only
|
have to worry about :exc:`KeyboardInterrupt` at the exact same
|
places where you already have to worry about :exc:`Cancelled`.
|
|
This setting has no effect if your program has registered a custom
|
SIGINT handler, or if :func:`run` is called from anywhere but the
|
main thread (this is a Python limitation), or if you use
|
:func:`open_signal_receiver` to catch SIGINT.
|
|
strict_exception_groups (bool): If true, nurseries will always wrap even a single
|
raised exception in an exception group. This can be overridden on the level of
|
individual nurseries. This will eventually become the default behavior.
|
|
Returns:
|
Whatever ``async_fn`` returns.
|
|
Raises:
|
TrioInternalError: if an unexpected error is encountered inside Trio's
|
internal machinery. This is a bug and you should `let us know
|
<https://github.com/python-trio/trio/issues>`__.
|
|
Anything else: if ``async_fn`` raises an exception, then :func:`run`
|
propagates it.
|
|
TN) rg Ú unrolled_runr/ r1 r$ r% r[ r3 r r´ rî ) rø r= r5 rf rÛ rù Ú__tracebackhide__r¾ ÚgenrB r' r/ r/ r1 r4 t s" Pü
|
r4 )r4 Ú host_uses_signal_set_wakeup_fdr= r5 rf rÛ c G sR t ||||}
|
d|
|
_d|
|
_|dkr&|}t|
|
|||t|
|
| | |dd} || j dS )a Start a "guest" run of Trio on top of some other "host" event loop.
|
|
Each host loop can only have one guest run at a time.
|
|
You should always let the Trio run finish before stopping the host loop;
|
if not, it may leave Trio's internal data structures in an inconsistent
|
state. You might be able to get away with it if you immediately exit the
|
program, but it's safest not to go there in the first place.
|
|
Generally, the best way to do this is wrap this in a function that starts
|
the host loop and then immediately starts the guest run, and then shuts
|
down the host when the guest run completes.
|
|
Args:
|
|
run_sync_soon_threadsafe: An arbitrary callable, which will be passed a
|
function as its sole argument::
|
|
def my_run_sync_soon_threadsafe(fn):
|
...
|
|
This callable should schedule ``fn()`` to be run by the host on its
|
next pass through its loop. **Must support being called from
|
arbitrary threads.**
|
|
done_callback: An arbitrary callable::
|
|
def my_done_callback(run_outcome):
|
...
|
|
When the Trio run has finished, Trio will invoke this callback to let
|
you know. The argument is an `outcome.Outcome`, reporting what would
|
have been returned or raised by `trio.run`. This function can do
|
anything you want, but commonly you'll want it to shut down the
|
host loop, unwrap the outcome, etc.
|
|
run_sync_soon_not_threadsafe: Like ``run_sync_soon_threadsafe``, but
|
will only be called from inside the host loop's main thread.
|
Optional, but if your host loop allows you to implement this more
|
efficiently than ``run_sync_soon_threadsafe`` then passing it will
|
make things a bit faster.
|
|
host_uses_signal_set_wakeup_fd (bool): Pass `True` if your host loop
|
uses `signal.set_wakeup_fd`, and `False` otherwise. For more details,
|
see :ref:`guest-run-implementation`.
|
|
For the meaning of other arguments, see `trio.run`.
|
|
TN)rk )r¾ r- r4 r2 r0 )rg r¿ r) r" rh r* ) rø r- r2 r4 rk r= r5 rf rÛ rù r¾ Z guest_stater/ r/ r1 Ústart_guest_runÝ s. =üüû rl iQ c
|
c s dt t< d}z>zÐ|s&| j j ¡ d| jkr<| j d¡ | j ¡ | j| j||fd ddd| _| jrâ| jrvd}n| j ¡ }| j |¡}t t d|t }d }| j rÌ| j ¡ d \} }
|
| |k râ| }t!j"}n| j#|k râ| j#}t!j$}d| jkrú| j d|¡ |V } | j% &| ¡ d| jkr&| j d|¡ | j '¡ } | j (| ¡rBd }|d k rÄ| jsÄ| sÄ|t!j"krª| j rÄ| j )d¡\} }| d | kr¨| j | = | *|¡ nqÄqfn|t!j$ksºt+| j ,¡ t-| j}| j ¡ t.rú|j/dd d
|
t0 1|¡ nt0 2¡ d k r| 3¡ |rb| 4¡ }|t_5d | jkr<| j d |¡ |j6}|j7}d |_6|_7d }z|j8 9||¡}W n~ t:k
|
r } zt;|j<}W 5 d }~X Y nR t=k
|
rè } z2|j>j?}t@tAD ] }
|
|j?}qºt
|
| B|¡}~W 5 d }~X Y nX |d k r| C||¡ d }n²| jDd 7 _D|tEkr*| *|¡ ntF|tGkrt| jHd 7 _H|jI|_J| jrj|| jKkrj| L¡ | M¡ nBtF|tNkr| C||jO¡ n$tPd Q|¡}| *||¡ |jRjS|_6~d| jkrÒ| j d|¡ t`5~~~qqbW nf tTk
|
r tU VtWd¡ Y nD tXk
|
r Y n. t=k
|
rJ } ztXd|W 5 d }~X Y nX W 5 tj ¡ | ¡ | jrt }t| j t
|
r| j j |_ t
|
|| _ X d S )NTZ
|
before_runz<init>rU r Zbefore_io_waitZ after_io_waitc S s | j S r. )r )Útr/ r/ r1 rE ¯ rF z unrolled_run.<locals>.<lambda>)r^ g à?Zbefore_task_stepr zºtrio.run received unrecognized yield message {!r}. Are you trying to use a library written for some other framework like asyncio? That won't work without some kind of compatibility shim.Zafter_task_stepzSTrio guest run got abandoned without properly finishing... weird stuff might happenz+internal error in Trio - please file a bug!)Yr¯ r r½ Ú__dict__Úclearr r r r[ r3 r rî r¨ r6 ÚwakeupZwakeup_on_signalsr5 r8 r= rK r÷ r} r? r r: rÀ ro rO r ÚmaxÚ _MAX_TIMEOUTr[ ÚkeysrU rV rc rW r$ Zprocess_eventsrM rx Zpeekitemrí rr Z _autojumprX Ú _ALLOW_DETERMINISTIC_SCHEDULINGÚsortrC ÚshuffleÚrandomÚreverser r r r r r4 r1 r r´ rô r6 r7 ÚrangeÚCONTEXT_RUN_TB_FRAMESÚwith_tracebackrO r r r r" r Z
|
abort_funcr rQ r r r! Ú final_outcomerÇ r§ r ÚthrowÚ GeneratorExitÚwarningsÚwarnÚRuntimeWarningr )r¾ rø rù rk ri Zkir' rN Z idle_primedr` rn Úeventsrw r^ r ÚbatchZ next_send_fnrB r| ÚmsgZstop_iterationZtask_excr= r< r/ r/ r1 rh > sì
|
|
|
ÿ
|
|
|
|
|
|
|
|
|
|
|
|
ýÿ
|
|
ÿÿ
|
|
rh c @ s e Zd Zdd ZdddZdS )Ú_TaskStatusIgnoredc C s dS )NÚTASK_STATUS_IGNOREDr/ rI r/ r/ r1 r¼ * s z_TaskStatusIgnored.__repr__Nc C s d S r. r/ )rJ r´ r/ r/ r1 r× - s z_TaskStatusIgnored.started)N)rP rQ rR r¼ r× r/ r/ r/ r1 r
) s r
c C s, zt jW S tk
|
r& tddY nX dS )zReturn the :class:`Task` object representing the current task.
|
|
Returns:
|
Task: the :class:`Task` that called :func:`current_task`.
|
|
z!must be called from async contextN)r½ r rI r¡ r/ r/ r/ r1 r 4 s r c C s t j ¡ S )aP Returns the current effective deadline for the current task.
|
|
This function examines all the cancellation scopes that are currently in
|
effect (taking into account shielding), and returns the deadline that will
|
expire first.
|
|
One example of where this might be is useful is if your code is trying to
|
decide whether to begin an expensive operation like an RPC call, but wants
|
to skip it if it knows that it can't possibly complete in the available
|
time. Another example would be if you're using a protocol like gRPC that
|
`propagates timeout information to the remote peer
|
<http://www.grpc.io/docs/guides/concepts.html#deadlines>`__; this function
|
gives a way to fetch that information so you can send it along.
|
|
If this is called in a context where a cancellation is currently active
|
(i.e., a blocking call will immediately raise :exc:`Cancelled`), then
|
returned deadline is ``-inf``. If it is called in a context where no
|
scopes have a deadline set, it returns ``inf``.
|
|
Returns:
|
float: the effective deadline, as an absolute time.
|
|
)r r¤ r r/ r/ r/ r1 Úcurrent_effective_deadlineB s r c à sl t I dH t } | jd7 _| jjs<| | jjkrh| jjrhtt d t
|
dd ¡I dH W 5 Q R X dS )a« A pure :ref:`checkpoint <checkpoints>`.
|
|
This checks for cancellation and allows other tasks to be scheduled,
|
without otherwise blocking.
|
|
Note that the scheduler has the option of ignoring this and continuing to
|
run the current task if it decides this is appropriate (e.g. for increased
|
efficiency).
|
|
Equivalent to ``await trio.sleep(0)`` (which is implemented by calling
|
:func:`checkpoint`.)
|
|
Nr )rN c S s t jjS r. )r' r r r\ r/ r/ r1 rE u rF z checkpoint.<locals>.<lambda>) r r r r¤ r r rQ r r r r' r ©r r/ r/ r1 ró ] s
|
ÿÿró c à sJ t } | jjs"| | jjkr8| jjr8t ¡ I dH ds8t| j d7 _ dS )a¶ Issue a :ref:`checkpoint <checkpoints>` if the calling context has been
|
cancelled.
|
|
Equivalent to (but potentially more efficient than)::
|
|
if trio.current_effective_deadline() == -inf:
|
await trio.lowlevel.checkpoint()
|
|
This is either a no-op, or else it allow other tasks to be scheduled and
|
then raises :exc:`trio.Cancelled`.
|
|
Typically used together with :func:`cancel_shielded_checkpoint`.
|
|
NFr )
|
r r¤ r r rQ r r' ró rr r r r/ r/ r1 Úcheckpoint_if_cancelledx s
|
ÿÿr Úwin32)ÚWindowsIOManager)Ú*ÚlinuxZepoll)ÚEpollIOManagerZkqueue)ÚKqueueIOManagerzunsupported platform)N)F)~rý r rw Úselectr° Ú threadingÚ collectionsr Ú
|
contextlibr r ÚenumZ contextvarsr Úmathr Útimer Útypingr r Zsniffior rS Úheapqr
|
r r Zsortedcontainersr rï r r r r Z _entry_queuer r Ú _exceptionsr r r Z_kir r r Z _multierrorr r Z_trapsr r r r r! r" Z
|
_asyncgensr# Z _thread_cacher$ Z_instrumentationr% r¸ r' Z_utilr( r) r* Ú version_infoZexceptiongroupr- rv ÚobjectrA r2 rt ÚRandomrC r? rz ÚsrB ÚEnumrU r\ rb rz r© r rË rØ rá rÙ r Úlocalr r½ r r" r rg r4 rl rr rh r
r r r ró r ÚplatformZ _io_windowsr rd Z_generated_io_windowsrL Z _io_epollr Z_generated_io_epollZ
|
_io_kqueuer Z_generated_io_kqueueÚNotImplementedErrorZ_generated_runZ_generated_instrumentationr/ r/ r/ r1 Ú<module> sÖ
|
D - R>6
|
c
|
, $*ú nö Z
|
l
|
|
|
|
