"""case 잠금 파일 (계획 2026-09-27 L6 §2.5 · D-L6-3 · 검토 F8). `///hook.lock` 에 `fcntl.flock(LOCK_EX)` — `LOCK_NB` 로 `LOCK_POLL_SECONDS` 마다 다시 시도하고, 한도 `timeout`(기본 `HOOK_LOCK_TIMEOUT_SECONDS` 1200 s — hub 다리 한도 900 s + 번들 다리 여유)을 넘기면 잡지 못한 채 `False` 를 내준다 (호출자가 `lock_timeout` 으로 보고한다). 대기 중 `LOCK_NOTICE_SECONDS` 마다 "같은 case 의 다른 훅을 기다리는 중… N 초째" 한 줄을 stderr 에 낸다. - 잠금 파일 부모는 `mkdir(parents=True)` 로 만들고, 파일은 **지우지 않는다** — 지우면 새 파일에 잠금을 거는 쪽과 옛 파일에 거는 쪽이 동시에 "잡았다" 고 믿는 경쟁이 생긴다. - `flock` 은 열린 파일 기술자에 걸린다 — 프로세스가 죽으면 커널이 푼다(잔여 잠금 없음). 같은 프로세스라도 따로 연 기술자끼리는 서로 막는다. 데이터 홈은 로컬 디스크 전제다(NFS 에서는 `flock` 이 의미가 없다 — 계획 R-L6-11). - hub 대상 run 의 두 다리 전부와 batch 끝 hub 다리(`hook.finish_batch`)를 감싼다. L6b `runs eval` 새 경로도 ①~⑤ 전부를 이 잠금 안에서 돈다(계획 §2.12 B4) — 그 경로가 부르는 `bundle_leg.ensure_run_bundle` 은 스스로 잠그지 않고 호출자가 쥔 잠금을 전제한다(같은 프로세스에서 다시 잡으면 위 규칙대로 자기 자신을 기다린다). 잠금 파일에는 아무것도 쓰지 않는다. `poc_bundle` 은 함수 안에서만 import 한다(D-L6-14). """ from __future__ import annotations import fcntl import os import time from collections.abc import Iterator from contextlib import contextmanager from pathlib import Path import click from solar_eval.hub_hook.types import ( HOOK_LOCK_TIMEOUT_SECONDS, LOCK_FILENAME, LOCK_NOTICE_SECONDS, LOCK_POLL_SECONDS, ) #: 잠금 파일 권한(내용은 비어 있다 — 권한은 데이터 홈의 다른 파일과 같게). LOCK_FILE_MODE = 0o644 def lock_path(account: str, case: str) -> Path: """잠금 파일 위치 `///hook.lock`. 슬러그가 틀리면 `DataConfigError`(경로 조각으로 쓰기 전에 막는다).""" from poc_bundle.data.case_ref import parse_case_ref from poc_bundle.home import hub_reports_dir account, case = parse_case_ref(f"{account}/{case}") return hub_reports_dir() / account / case / LOCK_FILENAME @contextmanager def case_lock( account: str, case: str, *, timeout: float = HOOK_LOCK_TIMEOUT_SECONDS ) -> Iterator[bool]: """case 하나의 배타 잠금. 한도 안에 잡으면 `True`, 넘기면 `False`(호출자가 `lock_timeout` 으로 보고). Raises: ValueError: `timeout` 이 음수일 때. DataConfigError: case 슬러그가 틀렸을 때(`poc_bundle.data.errors`). OSError: 잠금 파일을 만들거나 열 수 없을 때(hook 이 `lock_exception:` 으로 강등한다). """ if timeout < 0: raise ValueError(f"lock timeout must be >= 0, got {timeout}") path = lock_path(account, case) path.parent.mkdir(parents=True, exist_ok=True) fd = os.open(path, os.O_RDWR | os.O_CREAT, LOCK_FILE_MODE) try: held = _acquire(fd, timeout, f"{account}/{case}") try: yield held finally: if held: fcntl.flock(fd, fcntl.LOCK_UN) finally: os.close(fd) def _acquire(fd: int, timeout: float, case_ref: str) -> bool: """`LOCK_NB` 폴링으로 잠근다. 한도 안에 잡으면 True — 한도 0 이면 한 번만 시도한다.""" started = time.monotonic() next_notice = LOCK_NOTICE_SECONDS while True: try: fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB) except BlockingIOError: elapsed = time.monotonic() - started else: return True if elapsed >= timeout: return False if elapsed >= next_notice: _echo_waiting(case_ref, elapsed) next_notice += LOCK_NOTICE_SECONDS time.sleep(min(LOCK_POLL_SECONDS, max(timeout - elapsed, 0.0))) def _echo_waiting(case_ref: str, elapsed: float) -> None: """대기 안내 한 줄(stderr) — case 이름과 경과 초만.""" click.secho( f" 같은 case({case_ref})의 다른 훅을 기다리는 중… {int(elapsed)} 초째", fg="yellow", err=True, )