jCRUdZddlmZgdZddlZddlZddlZddlZddlm Z m Z ddl m Z ddl mZddlmZmZmZdd lmZdd lmZmZmZmZmZmZmZmZmZmZm Z dd l!m"Z"dd l#m$Z$dd l%m&Z&m'Z'm(Z(m)Z)ddl*m+Z+erddl,m-Z-m.Z.ddl#m/Z/eZ0de1d<ejda3de1d<Gdde4Z5Gdde5Z6GddejnZ8d$dZ9 d%dZ:e GddZ;e Gd d!Z@N?blocking is_singletonheartbeat_intervalstale_threshold poll_interval on_compromisec tt|td|}|ind|i} |st|||f|||||d| St |} |j 5|jj| } | | |jvrd|} t| tj} |j}|j|  t|||f|||||d| } |j| tj| k7r d} t| | |j| <nt| j dt|dk7s| j"|k7r-d| j d | j"d |d |} t%| || j&|k7rd |} t%| t)|||| cdddS#|j| wxYw#1swYyxYw) Ntimeoutr2)r-r.r/r0r1z2Singleton lock construction is already active for zOLock construction cannot continue after fork; construct a new lock in the childF) any_negativez$Singleton lock created with timeout=z , blocking=z, cannot be changed to timeout=zCSingleton lock created with a different on_compromise callback for )rrrsuper__call__rr(r'getr) RuntimeErrorosgetpidadddiscardrr4r- ValueError_on_compromise_validate_intervals)cls lock_filer4r-r.r/r0r1r2extra normalizedinstancemsgconstruction_pidconstruction_registry __class__s d/home/oem/CyberBrain26-unified/dev-env/.venv/lib/python3.12/site-packages/filelock/_soft_rw/_sync.pyr7z_SoftRWMeta.__call__7s; !!9g.#+/=1Q7# ")#5 /+    *  + ~~))*5H!B!BBNym\C&s++#%99; (+(I(I%%))*5 >$w/! "*%1+=(7&3   H*11*=99;"22kC&s++-5z*!("2"2G$W5AB$$0;8;K;K:LKX`XiXiWjk55d&Z&d+d'Z'xZ(S)?rSa Cross-process and cross-host reader/writer lock for shared filesystems. Use this class instead of :class:`~filelock.ReadWriteLock` when the lock file lives on a network filesystem (NFS, Lustre, HPC cluster shared storage). ``ReadWriteLock`` is backed by SQLite and cannot run on NFS because SQLite's ``fcntl`` locking is unreliable there. The lock's state is a log of immutable snapshots under ``foo.lock.rw/gen/``, each naming the writer and the readers holding the lock at generation ``N``. Every acquire, release, and eviction publishes the next snapshot with one atomic no-replace hard link, so no transition can be left half done by a crash on any host. Each participant also keeps ``foo.lock.rw/holders/``, a record whose nonce a daemon heartbeat thread rewrites every ``heartbeat_interval`` seconds. A contender evicts a member whose record has not changed for ``stale_threshold`` seconds of the contender's own monotonic clock; no clock is ever compared across hosts, so skew between hosts or against the file server cannot make a live holder look dead. Writer acquire is writer-preferring: a writer enters the snapshot as soon as no live writer is named, which blocks any new reader, then waits for the named readers to leave. Writer starvation is impossible. An expired holder is not fenced by the lock: a process paused past ``stale_threshold`` resumes believing it holds the lock until its next heartbeat reports the loss through ``on_compromise``. :attr:`generation` is a monotonic fencing token for the protected resource: a store that rejects writes carrying a lower generation than the highest it has accepted refuses such a holder. Reentrancy, upgrade/downgrade rules, thread pinning, and singleton caching by canonical path match :class:`~filelock.ReadWriteLock`. Forking invalidates the inherited instance in the child so the child cannot double-own the lock with its parent; ``release()`` on that instance is a no-op, and the child must construct a new instance if it needs a lock. Trust boundary: protects against same-UID non-cooperating processes (one host or cross-host) and same-host different-UID users via ``0o600`` / ``0o700`` permissions. Does not protect against root compromise or multi-tenant mounts where hostile co-tenants share the UID. :param lock_file: path to the lock file; the protocol directory lives next to it as ``.rw`` :param timeout: maximum wait time in seconds; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately on contention :param is_singleton: if ``True``, reuse existing instances for the same canonical path :param heartbeat_interval: seconds between heartbeat refreshes; default 30 s :param stale_threshold: seconds a holder record may stay unchanged before a contender evicts it; defaults to ``3 * heartbeat_interval``, matching etcd's ``LeaseKeepAlive`` convention :param poll_interval: seconds between acquire retries under contention; default 0.25 s :param on_compromise: called from the heartbeat thread with a :class:`~filelock.LeaseCompromise` when the hold is lost: a peer evicted it, or refreshes failed for long enough that a peer could have .. versionadded:: 3.27.0 .. versionchanged:: 3.33.0 The on-disk protocol is a generation log; earlier releases cannot share a lock path with this one. z5ClassVar[WeakValueDictionary[str, SoftReadWriteLock]]r'zClassVar[set[str]]r)c t|di|t|_t j |_t|_t|y)z !+F+,.'oo/,/E)S!rZTr*Nr+r,ctj|_t|||\}}}tj||_||_||_||_||_ ||_ t|j d|_ t|j |_tt j"|_t'|j|j |j|_||_t-t/j0t/j0|_d|_d|_d|_t:5|t<t?|<dddtA|y#1swYxYw)Nz.rwinternal transactionF)!r:r; _creator_pidr@fspathrBr4r-r/r0r1r_rootr_filesrtime monotonic_ledgerr_logr?_Locksr_Lock_locks_hold _compromise_closedr$r"idr) selfrBr4r-r.r/r0r1r2s rJ__init__zSoftReadWriteLock.__init__s!IIK=P > :O]!ii 2% & );&5$1#4>>2337 dnn- dnn- !$++t~~tzzJ +inn&6INNDTU #' 37"  ,'+N2d8 $ ,d# , ,s E,,E5ctjat|_tj |_t|_yN) r_rpr$r r'r`r(rar))rAs rJ_reset_class_after_forkz)SoftReadWriteLock._reset_class_after_forks4(nn.,.'oo/,/E)rZc|jj5|jdn|jjjcdddS#1swYyxYw)aF The generation at which the current hold was granted, or ``None`` when no lock is held. Generations are monotonic across all participants and hosts, so this is a fencing token: pass it to the protected resource and have the resource reject any operation carrying a lower generation than the highest it has accepted. That refuses a holder that paused past ``stale_threshold``, was evicted, and resumed. Removing the ``.rw`` directory starts a new log whose generations begin again at 1. .. versionadded:: 3.33.0 N)rqrerr participant generationrvs rJr}zSoftReadWriteLock.generationsH[[ ! ! U::-44::3I3I3T3T U U Us .AAcr|jj5|jcdddS#1swYyxYw)a How the current hold was lost, or ``None`` while it stands. Set by the heartbeat thread once a peer has evicted this holder or refreshes have failed for long enough that a peer could have. The holder should stop using the protected resource when it is set. Until the lost hold is released, acquiring on this instance raises :class:`RuntimeError` instead of joining it. .. versionadded:: 3.33.0 N)rqrersr~s rJ compromisezSoftReadWriteLock.compromises/[[ ! ! $## $ $ $s -6r-c#K|j|| d|jy#|jwxYww)a Context manager that acquires and releases a shared read lock. Falls back to instance defaults for *timeout* and *blocking* when ``None``. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default :raises RuntimeError: if a write lock is already held on this instance :raises Timeout: if the lock cannot be acquired within *timeout* seconds :raises TypeError: if *timeout* is a :class:`bool` or not a real number, or *blocking* is not a :class:`bool` :raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1`` rN) acquire_readreleaservr4r-s rJ read_lockzSoftReadWriteLock.read_locks5 'H5   LLNDLLNA,A>Ac#K|j|| d|jy#|jwxYww)a" Context manager that acquires and releases an exclusive write lock. Falls back to instance defaults for *timeout* and *blocking* when ``None``. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default :raises RuntimeError: if a read lock is already held, or a write lock is held by a different thread :raises Timeout: if the lock cannot be acquired within *timeout* seconds :raises TypeError: if *timeout* is a :class:`bool` or not a real number, or *blocking* is not a :class:`bool` :raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1`` rN) acquire_writerrs rJ write_lockzSoftReadWriteLock.write_lock+s5 7X6   LLNDLLNrc*|jd||S)uM Acquire a shared read lock. If this instance already holds a read lock, the lock level is incremented (reentrant). Attempting to acquire a read lock while holding a write lock raises :class:`RuntimeError` (downgrade not allowed). On the 0→1 transition the reader publishes its holder record, enters the next snapshot once no live writer is named, and starts a daemon heartbeat thread that rewrites the record's nonce every ``heartbeat_interval`` seconds so peers on other hosts do not evict it. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable; ``None`` uses the instance default :returns: a proxy that can be used as a context manager to release the lock :raises RuntimeError: if a write lock is already held on this instance, if this instance was invalidated by :func:`os.fork`, or if :meth:`close` was called :raises Timeout: if the lock cannot be acquired within *timeout* seconds :raises TypeError: if *timeout* is a :class:`bool` or not a real number, or *blocking* is not a :class:`bool` :raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1`` :raises SoftFileLockProtocolError: if a snapshot cannot be read without risking overlap, or the filesystem refuses the no-replace hard links the protocol commits with readr_acquirers rJrzSoftReadWriteLock.acquire_readAs4}}VWx}@@rZc*|jd||S)a Acquire an exclusive write lock. If this instance already holds a write lock from the same thread, the lock level is incremented (reentrant). Attempting to acquire a write lock while holding a read lock raises :class:`RuntimeError` (upgrade not allowed). Write locks are pinned to the acquiring thread: a different thread trying to re-enter also raises :class:`RuntimeError`. A writer enters the next snapshot as its writer as soon as no live writer is named, which blocks every new reader on every host, then waits for the readers that snapshot names to leave. Writer starvation is impossible: new readers see the named writer and wait behind it. :param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable; ``None`` uses the instance default :returns: a proxy that can be used as a context manager to release the lock :raises RuntimeError: if a read lock is already held, if a write lock is held by a different thread, if this instance was invalidated by :func:`os.fork`, or if :meth:`close` was called :raises Timeout: if the lock cannot be acquired within *timeout* seconds :raises TypeError: if *timeout* is a :class:`bool` or not a real number, or *blocking* is not a :class:`bool` :raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1`` :raises SoftFileLockProtocolError: if a snapshot cannot be read without risking overlap, or the filesystem refuses the no-replace hard links the protocol commits with writerrrs rJrzSoftReadWriteLock.acquire_write]s:}}Wg}AArZc||||S)a0 Return the singleton :class:`SoftReadWriteLock` for *lock_file*. :param lock_file: path to the lock file; the protocol directory lives next to it as ``.rw`` :param timeout: maximum wait time in seconds; ``-1`` means block indefinitely :param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable :returns: the singleton lock instance :raises ValueError: if an instance already exists for this path with different *timeout* or *blocking* values rr])rArBr4r-s rJget_lockzSoftReadWriteLock.get_lock|s(9g99rZc|jtjk7ry|jj5d|_ddd|j dy#1swYxYw)u Release any held lock and mark the instance closed. Idempotent. After calling this method the instance can no longer acquire locks — subsequent acquires raise :class:`RuntimeError`, and so does an acquire another thread is still waiting in, which gives up its claim instead of taking the lock. A fork-invalidated instance is closed without raising. NTforce)rgr:r;rqrertrr~s rJclosezSoftReadWriteLock.closesT    + [[ ! ! DL  4    s AA%Frc|jtjk7ry|jt j |y)a Release one level of the current lock. When the lock level reaches zero the heartbeat thread is stopped, the participant is committed out of the next snapshot, and its holder record is removed. On a fork-invalidated instance (that is, the child of a :func:`os.fork` call made while the parent held a lock) this method is a no-op so inherited ``with`` blocks can unwind cleanly in the child. :param force: if ``True``, release the lock completely regardless of the current lock level :raises RuntimeError: if no lock is currently held and *force* is ``False``, or if the calling thread holds no level of the current lock and *force* is ``False`` Nr)rgr:r;_releaser_ get_ident)rvrs rJrzSoftReadWriteLock.releases4    +  i))+5 9rZc.|j|||||S)N)r-holder cancel_checkr)rvrmoder4r-rs rJ_acquire_level_ofz#SoftReadWriteLock._acquire_level_ofs }}T7Xf[g}hhrZc*|j|dy)NFr)r)rvrs rJ_release_level_ofz#SoftReadWriteLock._release_level_ofs fE *rZcd|jx}duxr||jk(xs||jvSry)rrwrite_thread_id read_depths)rvrholds rJ_holds_level_ofz!SoftReadWriteLock._holds_level_ofs: "4/rVt?S?S5S5qW]aeaqaqWqrrZc|jj5|j}|3|r dddyd|jdt |d}t ||rd|_n#|j|||j||j dkDr dddyd|_dddjj |jtjurA|jjt|j dztj"|j$j'y#1swYxYw#|j$j'wxYw)NzCannot release a lock on (lock id: z) that is not heldrg?)r4)rqrerrrBrur9level_raise_if_not_holderleave_one_levelheartbeat_stopraheartbeat_threadr_current_threadjoinminr/ TIMEOUT_MAXr|leave)rv thread_idrrrFs rJrzSoftReadWriteLock._releasesA [[ ! ! ::D|    2$..1ARPTXJVhi"3'' ))$ :$$Y/zzA~  DJ & ! %$$I,D,D,FF%%**3t7N7NQT7TV_VkVk3l*m    " " $3  2    " " $s$EA$EE A!EEE-cp||jjk(ry|jdk(rE||jk7r6d|jdt |d|d|j}t ||jdk(r9||jvr*d|jdt |d|d}t |yy) NrzCannot release write lock on r) from thread  while it is held by thread rzCannot release read lock on z, which does not hold it)ridentrrrBrur9r)rvrrrFs rJrz&SoftReadWriteLock._raise_if_not_holders --33 3  99 I1E1E$E//?{2d8*U(k)EdFZFZE[] s# # 99 9D4D4D#D.t~~.>k"T(T(k)AC s# # $E rZ)rrcn|jtjk7rd|jd}t || |j n|}| |j n|}|tjn|}|jj5|jr|jt||}|j|j||cdddS ddd|dk(rdnt!j"|z}t%|jj&|||j(|st+|jd |j-||||||jj&j/S#1swYxYw#|jj&j/wxYw)NSoftReadWriteLock on z4 was invalidated by fork(); construct a new instancerrL)r-r4r1r)r-r)rgr:r;rBr9r4r-r_rrqrert _closed_errorrrr_validate_reentrantrk perf_counterrrfr1r_do_acquire_innerr)rvrr4r-rrrFdeadlines rJrzSoftReadWriteLock._acquires|    +)$..)99mnCs# #")/$,,w$,$44==(*0.$$&f [[ ! ! >||((**1'HMGzz%//f=  > >&  >#b=4d.?.?.AG.K# KK # #,,%  $..)t 3 .))$&8bn)o KK # # + + -' > >& KK # # + + -s AFFF &F4c4td|jdS)Nrz has been closed)r9rBr~s rJrzSoftReadWriteLock._closed_errors3DNN3CCSTUUrZc jj5jj||cdddS dddt j j |jtjjj j j j|||t'j(}t+d||dk(r|nd|dk(r|dini t- fdj.|dt1d |tj  d}jj5j2rj5}n) _d_ j8j;ddd| j%|t= S#1swYxYw#t$r6t!t"5 j%ddd#1swYxYwwxYw#t$r}d_|}Yd}~d}~wwxYw#1swYxYw) N)r0clockledgerlog)rr-rrrc(jSry)_refresh)rr|rvsrJz5SoftReadWriteLock._do_acquire_inner..Bs k4 @rZzfilelock-heartbeat-x)refreshinterval stop_eventname)rrrrr|rr last_refreshlock)rqrerrrrrjrir0rkrlrmrnpublish _wait_foradvance BaseExceptionrOSErrorrr_Event_Hold_HeartbeatThreadr/rurtrrsrstartr ) rvrrrr-rr start_errorerrorrr|s ` @@rJrz#SoftReadWriteLock._do_acquire_inners [[ ! ! >zz%//f= > >% >" KK JJ  00..<<     NN;..HcoN p__& &*goF4'+v~ 2#-@00%*2d8A,7  &) (-1 [[ ! ! (||"002 ! #' ())//1 (  "     !t,,u > > '" $!!# $  $   J%(!%DJ"'K( ( (s_G.G,H4HGH+H< HH H H1 H,'H4,H11H44H=c F|j}|J|j|k7rB|dk(rdnd}|dk(rdnd}d|d|jdt|d|d |d }t ||dk(rE||j k7r6d |jdt|d |d |j }t ||j x}t|j|||dk(r,|jj|ddz|j|<|xjdz c_ t|S)Nrr downgradeupgradeCannot acquire lock on rz): already holding a z lock (z not allowed)zCannot acquire write lock on rrrrr) rrrrBrur9rrs_lost_hold_errorrr8rr )rvrrropposite directionrFrs rJrz%SoftReadWriteLock._validate_reentrant`sLzz 99 "&&.wfH'+v~ 9I!$y0@ BtH:V%%-Jgi[ O s# # 7?v)=)==//?{2d8*U%h&B4CWCWBXZ s# #** *J 7"4>>4D D 6>'+'7'7';';FA'F'JD  V $ a !t,,rZct|s|jr|jtj}|r|||k\rt |j ||rt |j |j }|t|t||z d}tj||syy)Ng) rtrrkrrrBr1rmaxsleep)rv predicaterr-rnow sleep_fors rJrzSoftReadWriteLock._wait_forzs+||((**##%C 4dnn--'LNdnn--**I# 3x#~s+CD JJy !+rZc |j\}}|dk(rtj|_y|dk(r|j|ddytj|j z |j |jz k\r|j|d|yy#t$r}|j|d|Yd}~yd}~wwxYw)Nzrefresh-failedFokTlostevicted) heartbeat Exception_report_compromiserkrlrr0r/)rvr|routcomerfailures rJrzSoftReadWriteLock._refreshs  (224NGU d? $ 0D  f   # #D)T : >> d// /43G3G$JaJa3a a  # #D*:E B   # #D*:G D sB C&B>>Cc.|jj5|j|ur dddyt|j|j j ||}||_ddd|j|jyy#1swY(xYw)N)rBtokenreasonr) rqrerrrrBr|rrsr?)rvrrrrs rJrz$SoftReadWriteLock._report_compromises [[ ! ! *zz% * *)..0@0@0F0Fv]bJ *D   *    *    + + * *sB 4B  Bc~ttjtj|_d|_y)Nrd)ror_rprqrrr~s rJ_reset_after_fork_in_childz,SoftReadWriteLock._reset_after_fork_in_childs%inn&6INNDTU  rZ)rbobjectrRNonerK)rBrMr4rNr-rOr.rOr/rNr0rPr1rNr2rQrRrrRr)rR int | None)rRzLeaseCompromise | Nonery)r4rPr- bool | NonerRzGenerator[None])r4rPr-rrRr )rBrMr4rNr-rOrRrS)rrOrRr) rintrrr4rNr-rOrCallable[[], bool]rRr )rrrRr)rrrRrO)rrrrOrRr)rrrrrRr) rrr4rPr-rrrrCallable[[], bool] | NonerRr )rRr9) rrrrPrrr-rOrrrRr )rrrrrRr ) rrrrPr-rOrrrRr)r|rrrrRrO)rrrr!rzException | NonerRr))rTrUrV__doc__r r'rWr_r`r(rar)r^rw classmethodrzpropertyr}rrrrrrrrrrrrrrrrrrrrrrrXrYs@rJrSrSs2hI\H]JE]%ioo'O8;!#5="&$ !$((,#BF&$)&$&$  &$  &$"&$&&$&$@&$ &$P22 U U $ $QU*RV*ATXA8BUYB>:  :)::  :  ::*! (-:&ii!%i05iDHiXji i+s %8$2"26#.#.#.  #.  #.0#. #.JVC-C-C- C-  C-0C- C-J-4"%" "  " 0 " ".* ,rZrS) metaclassc<eZdZ dfd ZddZxZS)rcRt||d||_||_||_y)NT)rdaemon)r6rwr _interval _stop_event)rvrrrrrIs rJrwz_HeartbeatThread.__init__s- d40 !%rZcf |jj|jsR|js |jj y|jj|jsR|jj y#|jj wxYwry)rwaitrrrar~s rJrunz_HeartbeatThread.runs~ #&&++DNN;}}    " &&++DNN;    "D   "s5B%BB0) rrrrNrthreading.EventrstrrRrr)rTrUrVrwr rXrYs@rJrrs= &# & &$ &  &  &#rZrc @td|d|d|jdS)Nrrz: the current hold was lost (z$), release it before acquiring again)r9r)rBrrs rJrrs6  $y 3PQ[QbQbPcd, , rZctd|}t|r|dkrd|}t|td|||dzn td|}t|r||krd|d|}t|ttd|x}r|dkrd |}t|td|||k\rd |d |}t||||fS) Nr/rz4heartbeat_interval must be positive and finite, got r0z0stale_threshold must exceed heartbeat_interval (z) and be finite, got r1z/poll_interval must be positive and finite, got z-poll_interval must be below stale_threshold (z), got )rrr>r)r/r0r1rFs rJr@r@s""68JK & '+=+BDEWDXYo+-?@"1"9QxHY[j?k O $;M(M>?Q>RS""1!2 4 o Xo}%MMM NR_cdRd? Oo 6'=o=NgVcUdeo  ==rZc"eZdZUded<ded<y)ror#rerfN)rTrUrVrWr]rZrJrorosrZrocjeZdZUdZded<ded<ded<ded <d ed <d ed <ded<ded<ddZy)rzYEverything that exists only while a lock is held; ``None`` when the instance has no lock.rrrrrrzdict[int, int]rrr|rrr rrNrc |xjdzc_|jdk(r_||jvr|ntt |j}|jj |dz x}r||j|<yyy)Nrr)rrrnextiterpop)rvrownerdepths rJrz_Hold.leave_one_levelsz a 99 !*d.>.>!>IDdN^N^I_D`E((,,U3a77u7*/  '8 rZN)rrrRr)rTrUrVrrWrr]rZrJrrs8c J J&&##0rZrcttjD],}tt5|j dddd.y#1swY9xYw)NTr)listr"valuesrrr)rEs rJ_cleanup_all_instancesrsR..01) i  )   4  ( ) )) ) )s AA r)rBr rrrrrRr9)r/rNr0rPr1rNrRztuple[float, float, float]r)@r __future__r__lazy_modules__atexitr:r_rk contextlibrr dataclassesrrrtypingr r r weakrefr filelock._apir rrrrrrrrrrfilelock._errorrfilelock._leaserfilelock._soft_rw._protocolrrrrfilelock._soft_rw._storagercollections.abcrr r!r"rWrpr$typer&rSThreadrrr@rorrregister__all__r]rZrJr,s=c"  /!11'    $+PP.30EXEZBZ&4inn&6^6P$Pfo+od#y''#.>>0<>MR>>:      00 0,) &'&' rZ