vKgzSSKJr SSKrSSKJrJr SSKrSSKrSSKJ r SSK J r J r J r J r JrJr SSKJr \(aSSKJr SS K Jr SS KJr \R."S S 55r\\R2"S S S9"SS555r"SS\5r"SS5r\R."SS55r\"SS\55r\"SS\55r\R."SS55r \R2"S S S S9"SS\55r!\"S S!\!55r"\"S"S#\!55r#\R."S$S%55r$\"S&S'\55r%g)() annotationsN) TYPE_CHECKINGProtocol)_core)Abort ParkingLot RaiseCancelTadd_parking_lot_breakerenable_ki_protectionremove_parking_lot_breaker)final) TracebackType)Task)ParkingLotStatisticsc$\rSrSr%SrS\S'Srg)EventStatisticszAn object containing debugging information. Currently the following fields are defined: * ``tasks_waiting``: The number of tasks blocked on this event's :meth:`trio.Event.wait` method. int tasks_waitingN__name__ __module__ __qualname____firstlineno____doc____annotations____static_attributes__rJ/var/www/highfloat_scraper/venv/lib/python3.13/site-packages/trio/_sync.pyrrsr rF)repreqc\rSrSr%Sr\R "\SS9rS\ S'\R "SSS9r S\ S 'SS jr \ SS j5rSS jr SS jrSrg)Event*aA waitable boolean value useful for inter-task synchronization, inspired by :class:`threading.Event`. An event object has an internal boolean flag, representing whether the event has happened yet. The flag is initially False, and the :meth:`wait` method waits until the flag is True. If the flag is already True, then :meth:`wait` returns immediately. (If the event has already happened, there's nothing to wait for.) The :meth:`set` method sets the flag to True, and wakes up any waiters. This behavior is useful because it helps avoid race conditions and lost wakeups: it doesn't matter whether :meth:`set` gets called just before or after :meth:`wait`. If you want a lower-level wakeup primitive that doesn't have this protection, consider :class:`Condition` or :class:`trio.lowlevel.ParkingLot`. .. note:: Unlike `threading.Event`, `trio.Event` has no `~threading.Event.clear` method. In Trio, once an `Event` has happened, it cannot un-happen. If you need to represent a series of events, consider creating a new `Event` object for each one (they're cheap!), or other synchronization methods like :ref:`channels ` or `trio.lowlevel.ParkingLot`. Ffactoryinitz set[Task]_tasksdefaultr)bool_flagcUR$)z.Return the current value of the internal flag.r.selfs r!is_set Event.is_setIs zzr cUR(dKSUlURHn[R"U5 M URR 5 gg)z@Set the internal flag value to True, and wake any waiting tasks.TN)r.r*r rescheduleclearr2tasks r!set Event.setMsCzzDJ   &$ KK    r c6^^# TR(a'[RR5IShvN g[R "5mTR RT5 SUU4Sjjn[R"U5IShvN gN]N7f)zpBlock until the internal flag value becomes True. If it's already True, then this method returns immediately. Ncn>TRRT5 [RR$N)r*removerr SUCCEEDED)_r2r9s r!abort_fnEvent.wait..abort_fnbs% ""4({{,,,r )rAr returnr) r.triolowlevel checkpointr current_taskr*addwait_task_rescheduled)r2rBr9s` @r!wait Event.waitVsm ::--**, , ,%%'D KKOOD ! - ---h7 7 7 - 8s"3BBABBBBc:[[UR5S9$)zReturn an object containing debugging information. Currently the following fields are defined: * ``tasks_waiting``: The number of tasks blocked on this event's :meth:`wait` method. )r)rlenr*r1s r! statisticsEvent.statisticshsS-=>>r r0NrDr-rDNone)rDr)rrrrrattrsfieldr:r*rr.r3r rKrOrrr r!r%r%*sV2 Cerr1s r!acquire_HasAcquireRelease.acquirewssscgr>rr1s r!release_HasAcquireRelease.releaseysr rN)rDobject)rrrrrrZr]rrr r!rWrWts X*$r rWcP\rSrSr\SSj5r\SSj5rSrg)AsyncContextManagerMixin|c@# UR5IShvN gN7fr>)rZr1s r! __aenter__#AsyncContextManagerMixin.__aenter__}sllns c,# UR5 g7fr>)r])r2exc_type exc_value tracebacks r! __aexit__"AsyncContextManagerMixin.__aexit__s srN)r2rWrDrS) r2rWrgztype[BaseException] | NonerhzBaseException | NonerizTracebackType | NonerDrS)rrrrr rdrjrrr r!rara|sV ,((   r racB\rSrSr%SrS\S'S\S'S\S'S\S 'S rg ) CapacityLimiterStatisticsaAn object containing debugging information. Currently the following fields are defined: * ``borrowed_tokens``: The number of tokens currently borrowed from the sack. * ``total_tokens``: The total number of tokens in the sack. Usually this will be larger than ``borrowed_tokens``, but it's possibly for it to be smaller if :attr:`trio.CapacityLimiter.total_tokens` was recently decreased. * ``borrowers``: A list of all tasks or other entities that currently hold a token. * ``tasks_waiting``: The number of tasks blocked on this :class:`CapacityLimiter`'s :meth:`trio.CapacityLimiter.acquire` or :meth:`trio.CapacityLimiter.acquire_on_behalf_of` methods. rborrowed_tokens int | float total_tokenszlist[Task | object] borrowersrrNrrr r!rmrms!"""r rmc\rSrSrSrSSjrSSjr\SSj5r\RSSj5rSSjr \SSj5r \SS j5r \ SS j5r\ SS j5r\ SS j5r\ SS j5r\ SSj5r\ SSj5rSSjrSrg)CapacityLimiteraAn object for controlling access to a resource with limited capacity. Sometimes you need to put a limit on how many tasks can do something at the same time. For example, you might want to use some threads to run multiple blocking I/O operations in parallel... but if you use too many threads at once, then your system can become overloaded and it'll actually make things slower. One popular solution is to impose a policy like "run up to 40 threads at the same time, but no more". But how do you implement a policy like this? That's what :class:`CapacityLimiter` is for. You can think of a :class:`CapacityLimiter` object as a sack that starts out holding some fixed number of tokens:: limit = trio.CapacityLimiter(40) Then tasks can come along and borrow a token out of the sack:: # Borrow a token: async with limit: # We are holding a token! await perform_expensive_operation() # Exiting the 'async with' block puts the token back into the sack And crucially, if you try to borrow a token but the sack is empty, then you have to wait for another task to finish what it's doing and put its token back first before you can take it and continue. Another way to think of it: a :class:`CapacityLimiter` is like a sofa with a fixed number of seats, and if they're all taken then you have to wait for someone to get up before you can sit down. By default, :func:`trio.to_thread.run_sync` uses a :class:`CapacityLimiter` to limit the number of threads running at once; see `trio.to_thread.current_default_thread_limiter` for details. If you're familiar with semaphores, then you can think of this as a restricted semaphore that's specialized for one common use case, with additional error checking. For a more traditional semaphore, see :class:`Semaphore`. .. note:: Don't confuse this with the `"leaky bucket" `__ or `"token bucket" `__ algorithms used to limit bandwidth usage on networks. The basic idea of using tokens to track a resource limit is similar, but this is a very simple sack where tokens aren't automatically created or destroyed over time; they're just borrowed and then put back. c~[5Ul[5Ul0UlXlUR U:Xdegr>)r _lotr: _borrowers_pending_borrowersrq _total_tokens)r2rqs r!__init__CapacityLimiter.__init__s6L .1e=?)5!!\111r c S[U5SS[UR5SURS[UR5S3 $)Nz)idrNrxrzrwr1s r!__repr__CapacityLimiter.__repr__sU*2d8B-r#doo:N9OqQUQcQcPddjknosoxoxkyjz{DE Er cUR$)aThe total capacity available. You can change :attr:`total_tokens` by assigning to this attribute. If you make it larger, then the appropriate number of waiting tasks will be woken immediately to take the new tokens. If you decrease total_tokens below the number of tasks that are currently using the resource, then all current tasks will be allowed to finish as normal, but no new tasks will be allowed in until the total number of tasks drops below the new total_tokens. )rzr1s r!rqCapacityLimiter.total_tokenss!!!r c[U[5(dU[R:wa [ S5eUS:a [ S5eXlUR5 g)Nz'total_tokens must be an int or math.infrztotal_tokens must be >= 1) isinstancermathinf TypeError ValueErrorrz _wake_waiters)r2new_total_tokenss r!rqrsN*C005E5QEF F a 89 9- r cUR[UR5- nURR US9H7nURR UR RU55 M9 g)Ncount)rzrNrxrwunparkrIrypop)r2 availablewokens r!rCapacityLimiter._wake_waiterssZ&&T__)== YY%%I%6E OO   7 7 ; ;E B C7r c,[UR5$)z/The amount of capacity that's currently in use.)rNrxr1s r!roCapacityLimiter.borrowed_tokenss4??##r c4URUR- $)z/The amount of capacity that's available to use.)rqror1s r!available_tokens CapacityLimiter.available_tokens s  4#7#777r c^UR[RR55 g)zBorrow a token from the sack, without blocking. Raises: WouldBlock: if no tokens are available. RuntimeError: if the current task already holds one of this sack's tokens. N)acquire_on_behalf_of_nowaitrErFrHr1s r!acquire_nowaitCapacityLimiter.acquire_nowaits (()C)C)EFr cXR;a [S5e[UR5UR:a-UR(dURR U5 g[ Re)aGBorrow a token from the sack on behalf of ``borrower``, without blocking. Args: borrower: A :class:`trio.lowlevel.Task` or arbitrary opaque object used to record who is borrowing this token. This is used by :func:`trio.to_thread.run_sync` to allow threads to "hold tokens", with the intention in the future of using it to `allow deadlock detection and other useful things `__ Raises: WouldBlock: if no tokens are available. RuntimeError: if ``borrower`` already holds one of this sack's tokens. zEthis borrower is already holding one of this CapacityLimiter's tokensN)rx RuntimeErrorrNrzrwrIrE WouldBlockr2borrowers r!r+CapacityLimiter.acquire_on_behalf_of_nowaitsY&  &W  t $"4"4 4TYY OO   )// !r cz# UR[RR55IShvN gN7f)zBorrow a token from the sack, blocking if necessary. Raises: RuntimeError: if the current task already holds one of this sack's tokens. N)acquire_on_behalf_ofrErFrHr1s r!rZCapacityLimiter.acquire:s('' (B(B(DEEEs 1;9;c # [RR5IShvN URU5 [RR 5IShvN gN=N![R a [RR 5nXRU'URR5IShvN g![Ra URRU5 ef=ff=f7f)acBorrow a token from the sack on behalf of ``borrower``, blocking if necessary. Args: borrower: A :class:`trio.lowlevel.Task` or arbitrary opaque object used to record who is borrowing this token; see :meth:`acquire_on_behalf_of_nowait` for details. Raises: RuntimeError: if ``borrower`` task already holds one of this sack's tokens. N) rErFcheckpoint_if_cancelledrcancel_shielded_checkpointrrHryrwpark Cancelledr)r2rr9s r!r$CapacityLimiter.acquire_on_behalf_ofEsmm33555 =  , ,X 6--::< < < 6 = ==--/D,4 # #D ) iinn&&&>> ''++D1   s\"DA"DA&!DA$D$D&AD'C CC  D 1C==DDc^UR[RR55 g)zPut a token back into the sack. Raises: RuntimeError: if the current task has not acquired one of this sack's tokens. N)release_on_behalf_ofrErFrHr1s r!r]CapacityLimiter.releasebs !!$--"<"<">?r cXR;a [S5eURRU5 UR5 g)zPut a token back into the sack on behalf of ``borrower``. Raises: RuntimeError: if the given borrower has not acquired one of this sack's tokens. z@this borrower isn't holding any of this CapacityLimiter's tokensN)rxrr?rrs r!r$CapacityLimiter.release_on_behalf_ofms> ?? *R  x( r c[[UR5UR[ UR5[UR 5S9$)afReturn an object containing debugging information. Currently the following fields are defined: * ``borrowed_tokens``: The number of tokens currently borrowed from the sack. * ``total_tokens``: The total number of tokens in the sack. Usually this will be larger than ``borrowed_tokens``, but it's possibly for it to be smaller if :attr:`total_tokens` was recently decreased. * ``borrowers``: A list of all tasks or other entities that currently hold a token. * ``tasks_waiting``: The number of tasks blocked on this :class:`CapacityLimiter`'s :meth:`acquire` or :meth:`acquire_on_behalf_of` methods. )rorqrrr)rmrNrxrzlistrwr1s r!rOCapacityLimiter.statistics}s?")0++4??+dii.   r )rxrwryrzrqN)rqrprDstr)rDrp)rrprDrSrRrDr)rz Task | objectrDrS)rDrm)rrrrrr{rpropertyrqsetterrrorr rrrZrr]rrOrrr r!rtrts3l2E " "D $$88 G G""6FF==8@@   r rtc\rSrSrSrSS.SSjjrSSjr\SSj5r\SSj5r \ SS j5r \ SS j5r \ SS j5r SS jrS rg) SemaphoreiuA `semaphore `__. A semaphore holds an integer value, which can be incremented by calling :meth:`release` and decremented by calling :meth:`acquire` – but the value is never allowed to drop below zero. If the value is zero, then :meth:`acquire` will block until someone calls :meth:`release`. If you're looking for a :class:`Semaphore` to limit the number of tasks that can access some resource simultaneously, then consider using a :class:`CapacityLimiter` instead. This object's interface is similar to, but different from, that of :class:`threading.Semaphore`. A :class:`Semaphore` object can be used as an async context manager; it blocks on entry but not on exit. Args: initial_value (int): A non-negative integer giving semaphore's initial value. max_value (int or None): If given, makes this a "bounded" semaphore that raises an error if the value is about to exceed the given ``max_value``. N) max_valuec*[U[5(d [S5eUS:a [S5eUb0[U[5(d [S5eX!:a [S5e[R R 5UlXlX l g)Nzinitial_value must be an intrzinitial value must be >= 0z max_value must be None or an intz#max_values must be >= initial_value) rrrrrErFr rw_value _max_value)r2 initial_valuers r!r{Semaphore.__init__s---:; ; 1 9: :  i-- BCC( !FGG MM,,. # #r c~URcSnOSUR3nSURUS[U5SS3$)Nz , max_value=z)rrr)r2 max_value_strs r!rSemaphore.__repr__sE ?? "M*4??*;`__. This is a non-reentrant, single-owner lock. Unlike :class:`threading.Lock`, only the owner of the lock is allowed to release it. A :class:`Lock` object can be used as an async context manager; it blocks on entry but not on exit. rNrrrrrrrr r!rrs r rc\rSrSrSrSrg)StrictFIFOLockiu7 A variant of :class:`Lock` where tasks are guaranteed to acquire the lock in strict first-come-first-served order. An example of when this is useful is if you're implementing something like :class:`trio.SSLStream` or an HTTP/2 server using `h2 `__, where you have multiple concurrent tasks that are interacting with a shared state machine, and at unpredictable moments the state machine requests that a chunk of data be sent over the network. (For example, when using h2 simply reading incoming data can occasionally `create outgoing data to send `__.) The challenge is to make sure that these chunks are sent in the correct order, without being garbled. One option would be to use a regular :class:`Lock`, and wrap it around every interaction with the state machine:: # This approach is sometimes workable but often sub-optimal; see below async with lock: state_machine.do_something() if state_machine.has_data_to_send(): await conn.sendall(state_machine.get_data_to_send()) But this can be problematic. If you're using h2 then *usually* reading incoming data doesn't create the need to send any data, so we don't want to force every task that tries to read from the network to sit and wait a potentially long time for ``sendall`` to finish. And in some situations this could even potentially cause a deadlock, if the remote peer is waiting for you to read some data before it accepts the data you're sending. :class:`StrictFIFOLock` provides an alternative. We can rewrite our example like:: # Note: no awaits between when we start using the state machine and # when we block to take the lock! state_machine.do_something() if state_machine.has_data_to_send(): # Notice that we fetch the data to send out of the state machine # *before* sleeping, so that other tasks won't see it. chunk = state_machine.get_data_to_send() async with strict_fifo_lock: await conn.sendall(chunk) First we do all our interaction with the state machine in a single scheduling quantum (notice there are no ``await``\s in there), so it's automatically atomic with respect to other tasks. And then if and only if we have data to send, we get in line to send it – and :class:`StrictFIFOLock` guarantees that each task will send its data in the same order that the state machine generated it. Currently, :class:`StrictFIFOLock` is identical to :class:`Lock`, but (a) this may not always be true in the future, especially if Trio ever implements `more sophisticated scheduling policies `__, and (b) the above code is relying on a pretty subtle property of its lock. Using a :class:`StrictFIFOLock` acts as an executable reminder that you're relying on this property. rNrrr r!rrs;r rc.\rSrSr%SrS\S'S\S'Srg) ConditionStatisticsiaLAn object containing debugging information for a Condition. Currently the following fields are defined: * ``tasks_waiting`` (int): The number of tasks blocked on this condition's :meth:`trio.Condition.wait` method. * ``lock_statistics``: The result of calling the underlying :class:`Lock`\s :meth:`~Lock.statistics` method. rrrlock_statisticsrNrrr r!rrs ##r rc\rSrSrSrSSSjjrSSjrSSjrSSjrSSjr \ SS j5r SSS jjr SS jr SS jrS rg) ConditioniaA classic `condition variable `__, similar to :class:`threading.Condition`. A :class:`Condition` object can be used as an async context manager to acquire the underlying lock; it blocks on entry but not on exit. Args: lock (Lock): the lock object to use. If given, must be a :class:`trio.Lock`. If None, a new :class:`Lock` will be allocated and used. NcUc [5n[U5[La [S5eXl[R R 5Ulg)Nzlock must be a trio.Lock)rtyper_lockrErFr rw)r2locks r!r{Condition.__init__s? <6D :T !67 7 MM,,. r c6URR5$)zsCheck whether the underlying lock is currently held. Returns: bool: True if the lock is held, False otherwise. )rrr1s r!rCondition.lockedszz  ""r c6URR5$)zqAttempt to acquire the underlying lock, without blocking. Raises: WouldBlock: if the lock is currently held. )rrr1s r!rCondition.acquire_nowait szz((**r cT# URR5IShvN gN7f)zAcquire the underlying lock, blocking if necessary. Raises: BrokenResourceError: if the owner of the underlying lock exits without releasing. N)rrZr1s r!rZCondition.acquires jj  """s (&(c8URR5 g)zRelease the underlying lock.N)rr]r1s r!r]Condition.releases r c# [RR5URRLa [ S5eUR 5 URR5IShvN gN! [R"SS9 UR5IShvN SSS5 e!,(df  e=f=f7f)asWait for another task to call :meth:`notify` or :meth:`notify_all`. When calling this method, you must hold the lock. It releases the lock while waiting, and then re-acquires it before waking up. There is a subtlety with how this method interacts with cancellation: when cancelled it will block to re-acquire the lock before raising :exc:`Cancelled`. This may cause cancellation to be less prompt than expected. The advantage is that it makes code like this work:: async with condition: await condition.wait() If we didn't re-acquire the lock before waking up, and :meth:`wait` were cancelled here, then we'd crash in ``condition.__aexit__`` when we tried to release the lock we no longer held. Raises: RuntimeError: if the calling task does not hold the lock. BrokenResourceError: if the owner of the lock exits without releasing, when attempting to re-acquire. zmust hold the lock to waitNT)shield) rErFrHrrrr]rwr CancelScoperZr1s r!rKCondition.wait s2 == % % 'tzz/@/@ @;< <  )).." " " !!.lln$$/ /. sTACA91A72A96C7A99CB2#B&$B2) C2 C <CCc[RR5URRLa [ S5eUR RURR US9 g)zWake one or more tasks that are blocked in :meth:`wait`. Args: n (int): The number of tasks to wake. Raises: RuntimeError: if the calling task does not hold the lock. must hold the lock to notifyrN)rErFrHrrrrwrepark)r2ns r!notifyCondition.notifyEsN == % % 'tzz/@/@ @=> > 2r c[RR5URRLa [ S5eUR RURR 5 g)zWake all tasks that are currently blocked in :meth:`wait`. Raises: RuntimeError: if the calling task does not hold the lock. rN)rErFrHrrrrw repark_allr1s r! notify_allCondition.notify_allSsI == % % 'tzz/@/@ @=> > TZZ__-r cl[[UR5URR 5S9$)a.Return an object containing debugging information. Currently the following fields are defined: * ``tasks_waiting``: The number of tasks blocked on this condition's :meth:`wait` method. * ``lock_statistics``: The result of calling the underlying :class:`Lock`\s :meth:`~Lock.statistics` method. )rr)rrNrwrrOr1s r!rOCondition.statistics^s,#dii. JJ113  r )rrwr>)rz Lock | NonerQrR)r)rrrDrS)rDr)rrrrrr{rrrZr]r rKrrrOrrr r!rrsD /#+#""H 3 . r r)& __future__rrtypingrrrTrErrrr r r r r _utilrtypesrr_core._parking_lotrfrozenrdefiner%rWrarmrtrrrrrrrrr r!r!s" * #8   5U#E?E?$E?P%%  6m .m m `u&(u&u&p$U%0b (b 1b J 9  <Y<<~ $ $ $ A (A A r