# emulock

> **Tool `tools/live/emulock.py`** (program, The running game). Say who is using a shared emulator or VM, since when and for what, so two sessions do not drive one game at once.

Run it with `./gameframe run emulock ARGS` or `python3 tools/live/emulock.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/live/emulock.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool emulock` prints it.

```text
Say who is using a shared emulator or VM, since when and for what, so two sessions do not
drive one game at once.

Usage: emulock.py take NAME --who WHO --why TEXT [--dir DIR] [--force]
       emulock.py free NAME --who WHO [--dir DIR]
       emulock.py show [NAME] [--dir DIR]

  NAME     the emulator or VM: gf-vm, dosbox, the-windows-pc
  --who    the session or person: a session's name, an agent's name, a person's name
  --why    what for: "recording beltane-3", "testing a grip mod"
  --dir    where the locks live (default derived/locks). For a VM several machines use, put
           them inside the VM (run this there over SSH), so every session sees the same ones
  --force  take a lock another holder has, after asking them; the old note is printed

take writes DIR/NAME.lock with the holder, the time and the reason, and fails with exit 1,
naming the holder, when someone else holds it. Taking a lock you already hold renews it. free
removes your own lock (exit 1 when another holds it). show prints every lock, or one.

Why: two sessions in one emulated PC restarted each other's game, and a reference recording
was spoiled by another session's mods (docs/knowhow/mods-loaded-in-a-reference-recording.md,
docs/knowhow/context-emulated-pc.md). A lock note turns that into a question asked first.

It is a note between honest users, not a guard: it does not stop a process, and a script that
never calls take is not held back. Writes are atomic (a new file renamed into place).
Standard library only.
```