o 2j@slUdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZmZddlmZddlmZddlmZmZddlmZdd lmZdd lmZdd lmZdd l m!Z!erydd l"m#Z#m$Z$edZ%dZ&dZ'e(eddZ)e(eddZ*e j+dkoej,ej-vZ.eZ/de0d<e 1a2da3da4eddGdddZ5eGdddZ6eddGdddZ7eGdd d Z8Gd!d"d"e9Z:Gd#d$d$e:d%Z;Gd&d'd'e j<Z=dd(dOd0d1Z>dd(dPd3d4Z?dQd8d9Z@dd(dRd>d?ZAdd(dSd@dAZBdd(dSdBdCZCdTdEdFZDdUdGdHZEdVdIdJZFdVdKdLZGdVdMdNZHd$gZIdS)WzZCross-process and cross-host reader/writer lock built on :class:`SoftFileLock` primitives.) annotationsN)contextmanagersuppress) dataclass)Path) TYPE_CHECKINGLiteral)WeakValueDictionary)AcquireReturnProxy)Timeout) SoftFileLock)ensure_directory_exists)Callable Generator)readwritez.breaki O_NOFOLLOW O_NONBLOCKwin32,WeakValueDictionary[Path, SoftReadWriteLock]_all_instancesFT)frozenc@s&eZdZUded<ded<ded<dS)_PathsstrstaterreadersN__name__ __module__ __qualname____annotations__r!r!R/var/www/html/whisper/venv/lib/python3.10/site-packages/filelock/_soft_rw/_sync.pyr.  rc@s&eZdZUded<ded<ded<dS)_Locksthreading.Lockinternal transactionr rNrr!r!r!r"r$5r#r$c@s&eZdZUded<ded<ded<dS) _MarkerInfortokenintpidhostnameNrr!r!r!r"r(<r#r(c@sReZdZUdZded<ded<ded<ded <d ed <ded <d ed<ded<dS)_HoldzYEverything that exists only while a lock is held; ``None`` when the instance has no lock.r*level_Modemode int | Nonewrite_thread_idr marker_namebool is_readerr)_HeartbeatThreadheartbeat_threadthreading.Eventheartbeat_stopN)rrr__doc__r r!r!r!r"r-Cs  r-csBeZdZUded<ded< dddddd d dfddZZS) _SoftRWMetar _instancesr%_instances_lockT>@N?blocking is_singletonheartbeat_intervalstale_threshold poll_interval lock_filestr | os.PathLike[str]timeoutfloatrBr4rCrDrE float | NonerFreturnSoftReadWriteLockc s|stj|||||||dSt|}|jE|j|} | dur6tj|||||||d} | |j|<n| j|ks@| j|krTd| jd| jd|d|} t | | WdS1s`wYdS)NrAz$Singleton lock created with timeout=z , blocking=z, cannot be changed to timeout=) super__call__rresolver=r<getrIrB ValueError) clsrGrIrBrCrDrErF normalizedinstancemsg __class__r!r"rOUsD    $z_SoftRWMeta.__call__r>)rGrHrIrJrBr4rCr4rDrJrErKrFrJrLrM)rrrr rO __classcell__r!r!rWr"r;Qs r;c@s>eZdZUdZeZded<eZ dRdddddd dSddZ e dTdddUddZ e dTdddUddZ dTdddVd!d"ZdTdddVd#d$ZdWd%d&Zd'd(dXd*d+Ze dRdddYd,d-ZdZd0d1Zd[d4d5Zd\d6d7Zd]dd?Zd^dBdCZdWdDdEZd_dFdGZd`dIdJZdadLdMZd_dNdOZdWdPdQZdS)brMu Cross-process and cross-host reader/writer lock built on :class:`SoftFileLock` primitives. Use this class instead of :class:`~filelock.ReadWriteLock` when the lock file lives on a network filesystem (NFS, Lustre with ``-o flock``, HPC cluster shared storage). ``ReadWriteLock`` is backed by SQLite and cannot run on NFS because SQLite's ``fcntl`` locking is unreliable there. Layout on disk for a lock at ``foo.lock``: - ``foo.lock.state`` — a :class:`SoftFileLock` taken only during state transitions (microseconds). - ``foo.lock.write`` — writer marker; its presence means a writer is claiming or holding the lock. - ``foo.lock.readers/..`` — one file per reader. Each marker stores a random token (``secrets.token_hex(16)``), the holder's pid, and the holder's hostname. A daemon heartbeat thread refreshes ``mtime`` on every held marker. A marker whose mtime has not advanced in ``stale_threshold`` seconds may be evicted by any process on any host, giving correct behavior when a compute node crashes with a lock held. Writer acquire is two-phase and writer-preferring: phase 1 claims ``.write`` (blocking any new reader), phase 2 waits for existing readers to drain. Writer starvation is impossible. Reentrancy, upgrade/downgrade rules, thread pinning, and singleton caching by resolved path match :class:`~filelock.ReadWriteLock`. Forking while holding a lock invalidates the inherited instance in the child so the child cannot double-own the lock with its parent; ``release()`` on a fork-invalidated instance is a no-op, and the child must re-acquire 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, NTP tampering on same-UID cross-host nodes, or multi-tenant mounts where hostile co-tenants share the UID. :param lock_file: path to the lock file; sidecar state/write/readers live next to it :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 resolved path :param heartbeat_interval: seconds between heartbeat refreshes; default 30 s :param stale_threshold: seconds of ``mtime`` inactivity before a marker is stale; defaults to ``3 * heartbeat_interval``, matching etcd's ``LeaseKeepAlive`` convention :param poll_interval: seconds between acquire retries under contention; default 0.25 s .. versionadded:: 3.27.0 rr<r>Tr?Nr@rArGrHrIrJrBr4rCrDrErKrFrLNonec Cs@|dkr d|}t||dur|d}||kr&d|d|d}t||dkr3d|}t|t||_||_||_||_||_||_t |jd|jd |jd d |_ t |jt t t t|j jd d d|_d|_d|_d|_d|_t|tt|j<tWddS1swYdS)Nrz)heartbeat_interval must be positive, got z0stale_threshold must exceed heartbeat_interval (z <= )z$poll_interval must be positive, got z.statez.writez.readers)rrrr>rIr&r'rF)rRosfspathrGrIrBrDrErFr_pathsr r$ threadingLockr r_locks_readers_dir_fd_hold_fork_invalidated_closed_all_instances_lockrrrP_register_hooks) selfrGrIrBrCrDrErFrVr!r!r"__init__sH       "zSoftReadWriteLock.__init__rB bool | NoneGenerator[None]cc0|j||dz dVW|dS|w)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 rnN) acquire_readreleaserlrIrBr!r!r" read_lock zSoftReadWriteLock.read_lockccrq)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 rnN) acquire_writersrtr!r!r" write_lockrvzSoftReadWriteLock.write_lockr cC|jd||dS)uf 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 a daemon heartbeat thread is started that refreshes the reader marker's ``mtime`` every ``heartbeat_interval`` seconds so peers on other hosts do not evict the marker as stale. :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 rrn_acquirertr!r!r"rrszSoftReadWriteLock.acquire_readcCry)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`. Writer acquisition runs in two phases. Phase 1 atomically claims ``.write`` via ``O_CREAT | O_EXCL``, which immediately blocks any new reader on any host. Phase 2 waits for existing readers to drain. Writer starvation is impossible: new readers see ``.write`` during phase 2 and wait behind the pending writer. :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 rrnrzrtr!r!r"rw%szSoftReadWriteLock.acquire_writec Cs|jdd|jjB|jr WddSd|_|jdurDttt|jWdn1s4wYd|_WddSWddS1sOwYdS)u Release any held lock and release internal filesystem resources. Idempotent. After calling this method the instance can no longer acquire locks — subsequent acquires raise :class:`RuntimeError`. A fork-invalidated instance is closed without raising. TforceN) rsrer&rirfrOSErrorr`closerlr!r!r"r@s    "zSoftReadWriteLock.closeFr|r}cCs |jjW|jrd|_ WddS|j}|dur6|r& WddSd|jdt|d}t||rT)rBrI)rIrBrer&rhrGrrirg_validate_reentranttime perf_counterr'acquirer _do_acquire_innerrs)rlr0rIrBrVstartacquiredr!r!r"r{s2    zSoftReadWriteLock._acquireeffective_timeoutrc Cs&|jj|jdur||WdSWdn1s wY|dkr+dn||}td}|dkrC|j|||d\}}n |j|||d\}}t } t |j |j | dt |dd} |jjtd||dkrqtnd|||| | d |_Wdn1swY| t|d S) Nr>rdeadlinerBzfilelock-heartbeat-x)refreshinterval stop_eventnamer)r.r0r2r3r5r)r7r9lock)rer&rgrsecrets token_hex_acquire_writer_slot_acquire_reader_slotrcEventr6_refresh_markerrDrr- get_identrr ) rlr0rrrBrr)r3r5r heartbeatr!r!r"rs@      z#SoftReadWriteLock._do_acquire_innerc Cs|j}|dus J|j|kr7|dkrdnd}|dkrdnd}d|d|jdt|d|d |d }t||dkrZt}|jkrZd |jdt|d |d |j}t||jd7_t |dS)Nrr downgradeupgradezCannot acquire z lock on rz): already holding a z lock (z not allowed)zCannot acquire write lock on z) from thread z while it is held by thread rr) rgr0rGrrrcrr2r.r )rlr0ropposite directionrVcurr!r!r"rs,   z%SoftReadWriteLock._validate_reentrantr)rrtuple[str, bool]cstd fdd }d fdd }j|||dz j|||dWnty3tjjwjjdfS) NrLr4c sjj>tjjjtdtjjr WddSz tjjWnt y9YWddSwWddS1sEwYdS)NrEnowFT) rer_break_stale_markerrbrrEr _file_exists_atomic_create_markerFileExistsErrorr!rlr)r!r"try_claim_writers    z@SoftReadWriteLock._acquire_writer_slot..try_claim_writerc sxjj.tttjjWdn1swYt WdS1s5wYdSN) rerrr~_touchrbr_break_stale_readersr _any_readersr!rr!r"readers_drained_touchings  $zHSoftReadWriteLock._acquire_writer_slot..readers_drained_touchingrFrLr4)_open_readers_dir _wait_forr rrbr)rlr)rrBrrr!rr"rs      z&SoftReadWriteLock._acquire_writer_slotcsxtjdtjttj j dfdd }j |||ddur8dfSdfS) N.rLr4csjj6tjjjtdtjjr WddSdur,tdnt WddS1s=wYdS)NrFrT) rerrrbrrErrrr!rfull_reader_path reader_namerlr)r!r"try_claim_reader!s   $z@SoftReadWriteLock._acquire_reader_slot..try_claim_readerrTr) ruuiduuid4hexr`getpidrfrrrbrr)rlr)rrBrr!rr"rs z&SoftReadWriteLock._acquire_reader_slot predicateCallable[[], bool]cCsj |rdSt}|st|j|dur||krt|j|j}|dur/t|t||d}t|q)NTg)rrr rGrFminmaxsleep)rlrrrBr sleep_forr!r!r"r/s   zSoftReadWriteLock._wait_forcCst|jj}tt|jddWdn1swYt|jj}t |j s3t |j s>|jjd}t ||j dur[tr]tjttddBtB}t|jj||_ dSdSdS)Ni)r0zB exists but is not a directory or is a symlink; refusing to use it O_DIRECTORYr)rrbrrrmkdirr`lstatstatS_ISLNKst_modeS_ISDIRrrf_SUPPORTS_DIR_FDO_RDONLYgetattr _O_NOFOLLOWopen)rl readers_pathstrVflagsr!r!r"rCs  z#SoftReadWriteLock._open_readers_dircCs|D]}dSdS)NTF)_iter_reader_entries)rl_r!r!r"rQs zSoftReadWriteLock._any_readersGenerator[tuple[str, bool]]ccs|jdur/t|j}|D] }t|js|jdfVqWddS1s(wYdSt|jj}t|}|D]}t|jsNt||jdfVq=WddS1sZwYdS)a# Yield ``(name, dirfd_relative)`` pairs for every live reader marker. ``dirfd_relative`` is ``True`` when *name* should be passed to ``dir_fd=``-aware syscalls; ``False`` when *name* is a full path because dirfd-relative I/O is unavailable on this platform. NTF) rfr`scandir_is_housekeeping_namerrrbrr)rlitentryrr!r!r"rVs(       "z&SoftReadWriteLock._iter_reader_entriesrcCslg}z|D]\}}|||r|jndfqWn ty#YdSw|D] \}}t||j||dq&dS)N)rErr)rappendrfr~rrE)rlrnamesrdirfd_relativefdr!r!r"ris  z&SoftReadWriteLock._break_stale_readerscCs|jj&|j}|dur WddS|j}|j}|jr!|jnd}Wdn1s-wYt||d}|dur>dS|\}}|dusMt |j|sOdSz t ||dWdSt ybYdSt ykYdSw)NFrT) rer&rgr3r)r5rf _read_markerhmaccompare_digestrFileNotFoundErrorr~)rlrr3r)r read_resultinfo_mtimer!r!r"rss0    z!SoftReadWriteLock._refresh_markercCs:tttt|jjddd|_d|_d|_d|_ dS)Nr>r^r_T) r$rcrdr rbrrergrfrhrr!r!r"_reset_after_fork_in_childs z,SoftReadWriteLock._reset_after_fork_in_childrY)rGrHrIrJrBr4rCr4rDrJrErKrFrJrLr[r)rIrKrBrorLrp)rIrKrBrorLr rLr[)r}r4rLr[)rGrHrIrJrBr4rLrM)r0r/rIrKrBrorLr ) r0r/rrJrrJrBr4rLr )r0r/rLr )r)rrrKrBr4rLr)rrrrKrBr4rLr[r)rLr)rrJrLr[) rrrr:r r<r rcrdr=rmrrurxrrrwrrs classmethodrr{rrrrrrrrrrrr!r!r!r"rMsJ .2 *  " &  (      rM) metaclasscs(eZdZdfd d Zdd dZZS)r6rrrrJrr8rrrLr[cs&tj|dd||_||_||_dS)NT)rdaemon)rNrm_refresh _interval _stop_event)rlrrrrrWr!r"rms z_HeartbeatThread.__init__cCs:|j|js|s|jdS|j|jrdSdSr)rwaitrrrrr!r!r"runs  z_HeartbeatThread.run) rrrrJrr8rrrLr[r)rrrrmrrZr!r!rWr"r6s r6rrrr)rr1rLr[c CstjtjBtjBtB}tr|durtj||d|d}nt||d}z |dtdt d d}t ||Wt |dSt |w)Nir ascii) r`O_CREATO_EXCLO_WRONLYrrrrsocket gethostnameencoderr)rr)rrrcontentr!r!r"rs $r'tuple[_MarkerInfo | None, float] | Nonec CstjtBtB}ztr|durtj|||dnt||}Wn ty'YdSwz'zt|}t|t d}WntyHYWt |dSwWt |nt |wt ||j fS)Nrr) r`rr _O_NONBLOCKrrr~fstatr_MAX_MARKER_SIZEr_parse_marker_bytesst_mtime)rrrrrdatar!r!r"rs",   rrbytes_MarkerInfo | NonecCs|rt|tkr dSz|d}Wn tyYdSwtd|tj}|dur*dSt|dd}|dkr7dSt|d||ddS) Nru \A # start of string (?P [0-9a-f]{32} ) \n # 128-bit hex token (?P [1-9][0-9]{0,9} ) \n # decimal pid: no leading zero, ≤ 10 digits (?P [\x21-\x7e]{1,253}) # printable non-whitespace ASCII (RFC 1123 hostname limit) \n* # tolerate sloppy writers that append extra newlines \Z # end of string r+ ir)r,)r)r+r,) lenrdecodeUnicodeDecodeErrorrematchVERBOSEr*r()rtextr r+r!r!r"rs$  rrErJrr4c Cst||d}|dur dS|\}}|||krdS|dur$t||ddS|tdtdtd}ztrF|durFtj||||dnt ||Wn t yXYdSwt||d}|duredS|\} } | durut||ddSt |j | j sdS| |krdSt||ddS)NrFTrr) src_dir_fd dst_dir_fd)rr _BREAK_SUFFIXr`rrrrrenamerr~rrr)) rrErrr info_before mtime_before break_name read_after info_after mtime_afterr!r!r"rs>   "     rcCsftt%tr|durtj||dnt|WddSWddS1s,wYdSNr)rrrr`unlinkrrrr!r!r"r!s  "rcCs0tr|durtj|d|ddSt|ddSr)rr`utimerr!r!r"r*s rpathcCs0zt|}Wn tyYdSwt|jS)NF)r`rrrS_ISREGr)rrr!r!r"r1s   rcCs|dpt|vS)Nr) startswithr)rr!r!r"r9srcCs&tattD]}|q dSr)rcrdrjlistrvaluesrrUr!r!r"_reset_all_after_fork=s r$c CsJttD]}tt|jddWdn1swYqdS)NTr|)r!rr"r Exceptionrsr#r!r!r"_cleanup_all_instancesGs  r&cCs<ts ttdatsttdrtjtddadSdSdS)NTregister_at_fork)after_in_child) _atexit_registeredatexitregisterr&_fork_registeredhasattrr`r'r$r!r!r!r"rkMs  rk)rrr)rrr1rLr[)rrrr1rLr)rrrLr) rrrErJrrJrr1rLr4)rrrr1rLr[)rrrLr4)rrrLr4r)Jr: __future__rr*rr`r rrrsysrcrr contextlibrr dataclassesrpathlibrtypingrrweakrefr filelock._apir filelock._errorr filelock._softr filelock._utilr collections.abcrrr/rrrrrplatformrsupports_dir_fdrrr rdrjr)r,rr$r(r-typer;rMThreadr6rrrrrrrrr$r&rk__all__r!r!r!r"s~           1! #-