thds.mops 3.6.20250219172032__py3-none-any.whl

thds/mops/pure/core/deferred_work.py

@@ -0,0 +1,83 @@
+# Register expensive "only if we actually need to invoke the function" work to be performed later
+#
+# this could be _any_ kind of work, but is only uploads as of initial abstraction.
+# this basic idea was stolen from `pure.core.source` as a form of optimization for
+# uploading Sources and their hashrefs.
+import typing as ty
+from contextlib import contextmanager
+
+from thds import core
+from thds.core.stack_context import StackContext
+
+_DEFERRED_INVOCATION_WORK: StackContext[
+    ty.Optional[ty.Dict[ty.Hashable, ty.Callable[[], ty.Any]]]
+] = StackContext("DEFERRED_INVOCATION_WORK", None)
+logger = core.log.getLogger(__name__)
+
+
+@contextmanager
+def open_context() -> ty.Iterator[None]:
+    """Enter this context before you begin serializing your invocation. When perform_all()
+    is later called, any deferred work will be evaluated. The context should not be
+    closed until after return from the Shim.
+
+    The idea is that you'd call perform_all() inside your Shim which transfers
+    execution to a remote environment, but _not_ call it if you're transferring execution
+    to a local environment, as the upload will not be needed.
+
+    This is not re-entrant. If this is called while the dictionary is non-empty, an
+    exception will be raised. This is only because I can think of no reason why anyone
+    would want it to be re-entrant, so it seems better to raise an error. If for some
+    reason re-entrancy were desired, we could just silently pass if the dictionary already
+    has deferred work.
+    """
+    existing_work = _DEFERRED_INVOCATION_WORK()
+    assert existing_work is None, f"deferred work context is not re-entrant! {existing_work}"
+    with _DEFERRED_INVOCATION_WORK.set(dict()):
+        logger.debug("Opening deferred work context")
+        yield
+        logger.debug("Closing deferred work context")
+        work_unperformed = _DEFERRED_INVOCATION_WORK()
+        if work_unperformed:
+            logger.debug(
+                "some deferred work was not performed before context close: %s", work_unperformed
+            )
+
+
+@contextmanager
+def push_non_context() -> ty.Iterator[None]:
+    with _DEFERRED_INVOCATION_WORK.set(None):
+        yield
+
+
+def add(work_owner: str, work_id: ty.Hashable, work: ty.Callable[[], ty.Any]) -> None:
+    """Add some work to an open context. The work will be performed when perform_all() is
+    called. If there is no open context, perform the work immediately.
+
+    The work_owner should usually be the module __name__, but if multiple things
+    in a module need to add different types of tasks, then it can be anything
+    that would further disambiguate.
+
+    The work_id should be a unique id within the work_owner 'namespace'.
+    """
+    deferred_work = _DEFERRED_INVOCATION_WORK()
+    if deferred_work is None:
+        logger.debug("No open context - performing work %s immediately", work)
+        work()
+    else:
+        logger.debug("Adding work %s to deferred work %s", (work_owner, work_id), id(deferred_work))
+        deferred_work[(work_owner, work_id)] = work
+
+
+def perform_all() -> None:
+    """execute all the deferred work that has been added to the current context."""
+    work_items = _DEFERRED_INVOCATION_WORK()
+    if work_items:
+        logger.info("Performing %s items of deferred work", len(work_items))
+        for key, _result in core.parallel.yield_all(dict(work_items).items()):
+            # consume iterator but don't keep results in memory.
+            logger.debug("Popping deferred work %s from %s", key, id(work_items))
+            work_items.pop(key)
+
+        logger.debug("Done performing deferred work on %s", id(work_items))
+        assert not work_items, f"Some deferred work was not performed! {work_items}"

thds/mops/pure/core/entry/__init__.py

@@ -0,0 +1,2 @@
+from .route_result import route_return_value_or_exception  # noqa
+from .runner_registry import register_entry_handler, run_named_entry_handler  # noqa

thds/mops/pure/core/entry/main.py

@@ -0,0 +1,47 @@
+"""It's critical to keep this main function separate from everything
+in `.core`, because `.core` needs to be fully imported _before_ the
+remote function starts to run, otherwise you get infinite remote
+recursion without ever returning a result, since the core module ends
+up halfway imported and the effect of the IS_INSIDE_RUNNER_ENTRY.set(True) line
+gets erased when the final function module inevitably re-imports
+`.core` when being dynamically looked up, and core is not yet
+registered in sys.modules because it's still running `main`.
+
+Ask me how long it took to figure out what was going on there...
+"""
+
+import argparse
+import os
+import time
+from timeit import default_timer
+
+from thds.core.log import getLogger
+
+from ....__about__ import __version__
+from .. import metadata
+from .runner_registry import run_named_entry_handler
+
+logger = getLogger(__name__)
+
+
+def main() -> None:
+    """Routes the top level remote function call in a new process."""
+    start = default_timer()
+    start_timestamp = time.time()
+    logger.info(f"Entering remote process {os.getpid()} with installed mops version {__version__}")
+    parser = argparse.ArgumentParser(description="Unknown arguments will be passed to the named runner.")
+    parser.add_argument(
+        "runner_name",
+        help="Name of a known remote runner that can handle the rest of the arguments",
+    )
+    # TODO potentially allow things like logger context to be passed in as -- arguments
+    args, unknown = parser.parse_known_args()
+    run_named_entry_handler(args.runner_name, *unknown)
+    logger.info(
+        f"Exiting remote process {os.getpid()} after {(default_timer() - start)/60:.2f} minutes"
+        + metadata.format_end_of_run_times(start_timestamp, unknown)
+    )
+
+
+if __name__ == "__main__":
+    main()  # pragma: no cover

thds/mops/pure/core/entry/route_result.py

@@ -0,0 +1,66 @@
+"""Utilities that may be useful for a remote entry implementation for your Runner.
+
+None of them are required and may not be suitable for a given Runner implementation.
+"""
+
+import typing as ty
+
+from thds.core import log, scope
+
+from .. import deferred_work
+from ..output_naming import FunctionArgumentsHashUniqueKey, PipelineFunctionUniqueKey
+
+T_contra = ty.TypeVar("T_contra", contravariant=True)
+
+
+class ResultChannel(ty.Protocol[T_contra]):
+    """After remote invocation, respond with result.
+
+    A remote invocation can succeed with a result or fail with an exception.
+    """
+
+    def return_value(self, __return_value: T_contra) -> None:
+        ...  # pragma: no cover
+
+    def exception(self, __ex: Exception) -> None:
+        ...  # pragma: no cover
+
+
+logger = log.getLogger(__name__)
+_routing_scope = scope.Scope()
+
+
+@_routing_scope.bound
+def route_return_value_or_exception(
+    channel: ResultChannel[T_contra],
+    do_work_return_value: ty.Callable[[], T_contra],
+    pipeline_id: str = "",
+    pipeline_function_and_arguments_unique_key: ty.Optional[ty.Tuple[str, str]] = None,
+) -> None:
+    """The remote side of your runner implementation doesn't have to use this, but it's a reasonable approach."""
+    _routing_scope.enter(deferred_work.push_non_context())
+    # deferred work can be requested during result serialization, but because we don't want
+    # to leave a 'broken' result payload (one that refers to unperformed deferred work,
+    # maybe because of network or other failure), we simply don't open a deferred work
+    # context on the remote side, which forces all the work to be performed as it is
+    # added for deferral instead of actually being deferred.
+    #
+    # pushing this non-context is only necessary in the case of a thread-local
+    # 'remote' invocation - in all true remote invocations, there will be no context open.
+
+    _routing_scope.enter(log.logger_context(remote=pipeline_id))
+    if pipeline_function_and_arguments_unique_key:
+        pf_key, args_key = pipeline_function_and_arguments_unique_key
+        _routing_scope.enter(PipelineFunctionUniqueKey.set(pf_key))
+        _routing_scope.enter(FunctionArgumentsHashUniqueKey.set(args_key))
+    try:
+        # i want to _only_ run the user's function inside this try-catch.
+        # If mops itself has a bug, we should not be recording that as
+        # though it were an exception in the user's code.
+        return_value = do_work_return_value()
+    except Exception as ex:
+        logger.exception("Failure to run remote function. Transmitting exception...")
+        channel.exception(ex)
+    else:
+        logger.debug("Success running function remotely. Transmitting return value...")
+        channel.return_value(return_value)

thds/mops/pure/core/entry/runner_registry.py

@@ -0,0 +1,31 @@
+"""In theory, our core concept supports multiple different Runner 'types' being registered and used at the time of remote entry.
+
+In practice we only have a single Runner type registered, the MemoizingPicklingRunner.
+"""
+
+import typing as ty
+
+from thds.core import stack_context
+
+RUNNER_ENTRY_COUNT = stack_context.StackContext("runner_entry_count", 0)
+
+
+def entry_count() -> int:
+    return RUNNER_ENTRY_COUNT()
+
+
+class EntryHandler(ty.Protocol):
+    def __call__(self, *__args: str) -> ty.Any:
+        ...  # pragma: nocover
+
+
+ENTRY_HANDLERS: ty.Dict[str, EntryHandler] = dict()
+
+
+def register_entry_handler(name: str, mh: EntryHandler) -> None:
+    ENTRY_HANDLERS[name] = mh
+
+
+def run_named_entry_handler(name: str, *args: str) -> None:
+    with RUNNER_ENTRY_COUNT.set(RUNNER_ENTRY_COUNT() + 1):
+        ENTRY_HANDLERS[name](*args)

thds/mops/pure/core/file_blob_store.py

@@ -0,0 +1,120 @@
+import os
+import shutil
+import typing as ty
+from contextlib import contextmanager
+from pathlib import Path
+
+from thds.core import config, log
+from thds.core.files import FILE_SCHEME, atomic_write_path, path_from_uri, remove_file_scheme, to_uri
+from thds.core.link import link
+
+from ..core.types import AnyStrSrc, BlobStore
+
+MOPS_ROOT = config.item("control_root", default=Path.home() / ".mops")
+logger = log.getLogger(__name__)
+
+
+@contextmanager
+def atomic_writable(desturi: str, mode: str = "wb") -> ty.Iterator[ty.IO[bytes]]:
+    with atomic_write_path(desturi) as temppath:
+        with open(temppath, mode) as f:
+            yield f
+
+
+def _link(path: Path, remote_uri: str) -> None:
+    dest = path_from_uri(remote_uri)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    assert link(path, dest), f"Link {path} to {remote_uri} failed!"
+
+
+def _put_bytes_to_file_uri(remote_uri: str, data: AnyStrSrc) -> None:
+    """Write data to a local path. It is very hard to support all the same inputs that ADLS does. :("""
+    path = None
+    if isinstance(data, str):
+        path = Path(data)
+        if not path.exists():  # wasn't _actually_ a Path
+            path = None
+    elif isinstance(data, Path):
+        path = data
+    if path:
+        _link(path, remote_uri)
+    elif isinstance(data, bytes):
+        with atomic_writable(remote_uri, "wb") as f:
+            f.write(data)
+    elif isinstance(data, str):
+        with atomic_writable(remote_uri, "w") as f:
+            f.write(data)  # type: ignore
+    else:
+        # if this fallback case fails, we may need to admit defeat for now,
+        # and follow up by analyzing the failure and adding support for the input data type.
+        with atomic_writable(remote_uri, "wb") as f:
+            for block in data:  # type: ignore
+                f.write(block)
+
+
+class FileBlobStore(BlobStore):
+    def control_root(self, uri: str) -> str:
+        local_root = MOPS_ROOT()
+        local_root.mkdir(exist_ok=True)
+        return to_uri(local_root)
+
+    def readbytesinto(self, remote_uri: str, stream: ty.IO[bytes], type_hint: str = "bytes") -> None:
+        with path_from_uri(remote_uri).open("rb") as f:
+            shutil.copyfileobj(f, stream)  # type: ignore
+
+    def getfile(self, remote_uri: str) -> Path:
+        p = path_from_uri(remote_uri)
+        if not p.exists():
+            logger.error(f"{remote_uri} does not exist. Parent = {p.parent}")
+            try:
+                logger.error(list(p.parent.glob("*")))
+            except FileNotFoundError:
+                logger.error(f"{p.parent} does not exist either!")
+            raise FileNotFoundError(f"{remote_uri} does not exist")
+        return p
+
+    def putbytes(self, remote_uri: str, data: AnyStrSrc, type_hint: str = "bytes") -> None:
+        """Upload data to a remote path."""
+        logger.debug(f"Writing {type_hint} to {remote_uri}")
+        _put_bytes_to_file_uri(remote_uri, data)
+
+    def putfile(self, path: Path, remote_uri: str) -> None:
+        _link(path, remote_uri)
+
+    def exists(self, remote_uri: str) -> bool:
+        return path_from_uri(remote_uri).exists()
+
+    def join(self, *parts: str) -> str:
+        return os.path.join(*parts)
+
+    def split(self, uri: str) -> ty.List[str]:
+        """Splits a given URI into its constituent parts"""
+        path = remove_file_scheme(uri)
+        # normalize the path to handle redundant slashes
+        normalized_path = os.path.normpath(path)
+
+        parts = normalized_path.split(os.sep)
+
+        # remove any empty parts that might be created due to leading slashes
+        parts = [part for part in parts if part]
+
+        parts = [f"{FILE_SCHEME}/"] + parts
+
+        return parts
+
+    def is_blob_not_found(self, exc: Exception) -> bool:
+        return isinstance(exc, FileNotFoundError)
+
+
+_STATELESS_BLOB_STORE = FileBlobStore()
+
+
+def get_file_blob_store(uri: str) -> ty.Optional[FileBlobStore]:
+    if uri.startswith(FILE_SCHEME):
+        return _STATELESS_BLOB_STORE
+
+    # special case for things where somebody forgot the file:// scheme.
+    # we're the 'first' registered blob store, so we're the last ones to be asked
+    # and this shouldn't cause a significant performance penalty since everything else
+    # with a scheme will get picked up first.
+    return _STATELESS_BLOB_STORE

thds/mops/pure/core/lock/__init__.py

@@ -0,0 +1,7 @@
+from ._acquire import acquire  # noqa: F401
+from .maintain import (  # noqa: F401
+    CannotMaintainLock,
+    launch_daemon_lock_maintainer,
+    remote_lock_maintain,
+)
+from .types import LockAcquired  # noqa: F401

thds/mops/pure/core/lock/_acquire.py

@@ -0,0 +1,192 @@
+"""The intent of this module is to provide a best-effort "lock"
+that can be built on top of just `getbytes` and `putbytes` operations.
+
+It is important to note that this lock, while it should work under nearly all
+circumstances, is not actually a true lock - it is _possible_ for multiple holders of the
+lock to believe that they hold it exclusively, under degenerate conditions involving very
+slow networks. Therefore, it should only be used as a performance optimization, and not in
+cases where absolute application correctness depend upon an exclusive lock with full
+guarantees.
+
+While it is possible that a lock may be acquired multiple times, the _more likely_ failure
+scenario is contention for the lock. There is a built in safety margin to reduce cases of
+multiple lock acquirers, and with a very large number of lockers, it is possible that no
+acquirer will ever get to see its own write 'persist' long enough to determine that it has
+the lock.
+
+Again, this algorithm is _not_ designed to be a perfect lock - only to make it relatively
+efficient for a single caller to acquire a lock and maintain it for a period of time while
+other potential acquirers instead determine that they ought to wait for the lock to be
+released.
+"""
+
+import time
+import timeit
+import typing as ty
+from datetime import datetime, timedelta
+from uuid import uuid4
+
+from thds import humenc
+from thds.core import log
+
+from . import _funcs
+from .read import get_writer_id, make_read_lockfile
+from .types import LockAcquired, LockContents
+from .write import LockfileWriter, make_lock_contents
+
+logger = log.getLogger(__name__)
+
+
+def acquire(  # noqa: C901
+    lock_dir_uri: str,
+    *,
+    expire: timedelta = timedelta(seconds=30),
+    acquire_margin: timedelta = timedelta(seconds=0.0),
+    debug: bool = True,
+    block: ty.Optional[timedelta] = timedelta(seconds=0),
+) -> ty.Optional[LockAcquired]:
+    """Attempt to acquire an expiring lock.
+
+    Return a callable suitable for 'maintaining the lock as active' if the lock was
+    acquired, plus a Callable suitable for releasing the lock - otherwise, return None to
+    indicate that the lock is not owned.
+
+    The lock_dir_uri must be identical across multiple processes.
+
+    It is strongly recommended that expire and acquire_margin also be identical
+    across all processes attempting to acquire the same lock.
+
+    It is up to the caller to call `lock.maintain` at regular intervals less than
+    `expire`.  It is polite and more efficient for other acquirers for you to call
+    `lock.release` when the lock is no longer needed.
+
+    A lock that has not been updated in 'expire' seconds is considered 'released' and may
+    be acquired by any other process attempting to acquire it. If you do not `.maintain()`
+    the lock, you will lose it.
+
+    `acquire_margin` is the minimum amount of time that will be waited after attempting to
+    acquire the lock, to confirm that no other writer has also attempted to acquire
+    it. This should be scaled to be longer than the longest delay you expect _any_
+    candidate process to experience between checking the lock uri, finding it acquirable,
+    and successfully writing back to the lock uri itself. If the default value (0) is
+    provided, then the acquire_margin will be determined automatically to be twice the
+    amount of time elapsed between the beginning of the check and the end of the write. If
+    you have acquirers accessing this from very different environments, it may be safer to
+    specify a higher acquire_margin that will be closer to the largest latency you expect
+    any of your clients to experience.
+
+    `block` is the _minimum_ amount of time to wait before returning None if the lock
+    cannot be required. A zero length block will cause acquire to return None after the
+    first unsuccessful attempt. Passing block=None will block until first acquisition.
+
+    If you fail to acquire the lock and want to try again, it is recommended that you call
+    this at spaced intervals, not in a tight loop, in order to avoid performance issues.
+
+    """
+    if acquire_margin * 2 > expire:
+        # You should not be waiting nearly as much time as it would take for the lock to
+        # become expire to decide that you have acquired the lock.
+        #
+        # If network or other delays are encountered, other candidate acquirers will end
+        # up convinced that the lock has gone expire, right about the time you decide you
+        # have acquired it.
+        raise ValueError(
+            f"Acquire margin ({acquire_margin.total_seconds()})"
+            f" must be less than half the expire time ({expire.total_seconds()})."
+        )
+
+    acquire_margin_s = acquire_margin.total_seconds()
+    if acquire_margin_s < 0:
+        raise ValueError(f"Acquire margin may not be negative: {acquire_margin_s}")
+
+    start = _funcs.utc_now()
+
+    my_writer_id = humenc.encode(uuid4().bytes)
+
+    lockfile_writer = LockfileWriter(
+        my_writer_id,
+        lock_dir_uri,
+        make_lock_contents(my_writer_id, expire),
+        expire.total_seconds(),
+        debug=debug,
+    )
+
+    read_lockfile = make_read_lockfile(_funcs.make_lock_uri(lock_dir_uri))
+
+    def is_released(lock_contents: LockContents) -> bool:
+        return bool(lock_contents.get("released_at"))
+
+    def is_fresh(lock_contents: LockContents) -> bool:
+        written_at_str = lock_contents.get("written_at")
+        if not written_at_str:
+            # this likely won't happen in practice b/c we check released first.
+            return False  # pragma: no cover
+        lock_expire_s = lock_contents["expire_s"]
+        if round(lock_expire_s, 4) != round(expire.total_seconds(), 4):
+            logger.warning(
+                f"Remote lock {lock_dir_uri} has expire duration {lock_expire_s},"
+                f" which is different than the local configuration {expire}."
+                " This may lead to multiple simultaneous acquirers on the lock."
+            )
+        return datetime.fromisoformat(written_at_str) + expire >= _funcs.utc_now()
+
+    acquire_delay = 0.0
+
+    def determine_acquire_delay(before_read: float) -> float:
+        # decide how long we're going to wait.
+        read_write_delay = timeit.default_timer() - before_read
+        if acquire_margin_s and read_write_delay > acquire_margin_s:
+            logger.warning(
+                f"It took longer ({read_write_delay}) than the acquire margin"
+                " between the lock check and completing the lock write."
+                " There is danger that another process may think it has acquired the lock."
+                " You should make the acquire_margin longer to reduce the chances of this happening."
+            )
+        auto_acquire_delay = read_write_delay * 2
+        # pick the larger of the two, because if we're encountering bad latency, we should
+        # be waiting longer to make sure that we don't 'think we won' because of latency.
+        return max(acquire_margin_s, auto_acquire_delay)
+
+    while True:
+        before_read = timeit.default_timer()
+        maybe_lock_contents = read_lockfile()
+        if maybe_lock_contents:
+            lock = maybe_lock_contents
+            if is_released(lock):
+                logger.debug("Lock %s was released - attempting to lock", lock_dir_uri)
+            elif not is_fresh(lock):
+                logger.debug("Lock %s has expired - will attempt to steal it!", lock_dir_uri)
+            elif get_writer_id(lock) == my_writer_id:
+                # LOCK ACQUIRED!
+                lockfile_writer.mark_acquired()
+                # You still need to maintain it by calling .maintain() periodically!
+                return lockfile_writer
+
+            else:
+                # lock is fresh and held by another acquirer - failed to acquire!
+                if acquire_delay:
+                    logger.info(f"Lost race for lock {lock_dir_uri}")
+                    # this is info (not debug) because we expect it to be rare.
+                    acquire_delay = 0.0
+                if block is not None and _funcs.utc_now() > start + block:
+                    return None
+
+                time.sleep(0.2)
+                # just a short sleep before we try again - this probably doesn't need to
+                # be configurable, since anyone wanting different behavior can just pass
+                # block=0.0 and then do the polling themselves.
+                continue
+        else:
+            logger.debug("Lock %s does not exist - will attempt to lock it.", lock_dir_uri)
+
+        # lock has expired or does not exist - attempt to acquire it by writing!
+        lockfile_writer.write()
+
+        # wait for a long enough time that we feel confident we were the last writer and
+        # not just the fastest write-then-reader.
+        acquire_delay = determine_acquire_delay(before_read)
+        logger.debug(
+            "Waiting %s seconds before checking lock to see if we acquired it...", acquire_delay
+        )
+        time.sleep(acquire_delay)
+        # go back to the beginning of the loop, and see if we managed to acquire the lock!

thds/mops/pure/core/lock/_funcs.py

@@ -0,0 +1,37 @@
+import json
+import typing as ty
+from datetime import datetime, timezone
+
+from thds.core import log
+
+from ..types import BlobStore
+from ..uris import lookup_blob_store
+
+logger = log.getLogger(__name__)
+
+
+def utc_now() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def write(blob_store: BlobStore, lock_uri: str, lock_bytes: bytes) -> None:
+    try:
+        blob_store.putbytes(lock_uri, lock_bytes, type_hint="application/mops-lock")
+    except Exception:
+        logger.error(f"Failed to write lock at {lock_uri}")
+        raise
+
+
+def json_dumpb(contents: ty.Mapping) -> bytes:
+    return json.dumps(contents, indent=2).encode()
+
+
+def store_and_lock_uri(lock_dir_uri: str) -> ty.Tuple[BlobStore, str]:
+    blob_store = lookup_blob_store(lock_dir_uri)
+    lock_uri = blob_store.join(lock_dir_uri, "lock.json")
+    return blob_store, lock_uri
+
+
+def make_lock_uri(lock_dir_uri: str) -> str:
+    _, lock_uri = store_and_lock_uri(lock_dir_uri)
+    return lock_uri

thds/mops/pure/core/lock/cli.py

@@ -0,0 +1,73 @@
+import argparse
+import time
+import typing as ty
+from pathlib import Path
+
+from . import _acquire
+
+
+def _writer(out_times_path: Path) -> ty.Callable[[float, float], None]:
+    _acquire.logger.info(f"Will write Lock Times to {out_times_path}")
+    out_times_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def write_times(after_acquired: float, before_released: float) -> None:
+        _acquire.logger.info(f"..........appending {after_acquired},{before_released}")
+        with out_times_path.open("a") as f:
+            f.write(f"{after_acquired},{before_released}\n")
+
+    return write_times
+
+
+def acquire_and_hold_once(
+    lock_uri: str, hold_once_acquired_s: float, out_times_path: ty.Optional[Path]
+) -> None:
+    if out_times_path:
+        write_times = _writer(out_times_path)
+    else:
+        write_times = lambda x, y: None  # noqa: E731
+
+    # we want more verbose logging when using the CLI.
+    _acquire.logger.debug = _acquire.logger.info  # type: ignore
+
+    _acquire.logger.info(f"Beginning lock acquisition on {lock_uri}")
+    lock_owned = _acquire.acquire(lock_uri, block=None)
+    assert lock_owned
+    when_lock_acquired = time.time()
+    # we're using time, not timeit.default_timer, because we care about time
+    # differences between multiple processes on the same system, so we can compare
+    # them afterward.
+    time_until_release = when_lock_acquired + hold_once_acquired_s - time.time()
+    while time_until_release > 0:
+        lock_owned.maintain()
+        time.sleep(min(time_until_release, 4))
+        # don't wake up to maintain a lot - every 4 seconds is enough for the default 30s expiry.
+        time_until_release = when_lock_acquired + hold_once_acquired_s - time.time()
+
+    write_times(when_lock_acquired, time.time())
+    lock_owned.release()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("lock_uri", help="URI to the lockfile")
+    parser.add_argument(
+        "--hold-once-acquired-s",
+        "-t",
+        type=float,
+        default=20.0,
+        help="Time in seconds to hold the lock once acquired.",
+    )
+    parser.add_argument(
+        "--out-times",
+        type=Path,
+        default=None,
+        help="Write out the periods of time the lock was fully held (after acquire, before release) to this file.",
+    )
+
+    args = parser.parse_args()
+
+    acquire_and_hold_once(args.lock_uri, args.hold_once_acquired_s, args.out_times)
+
+
+if __name__ == "__main__":
+    main()