SCRYMAMEReferenceMachinelog_waitAlso in DOSBox-X

MAMEMachine

log_wait

Wait until a log line matches a pattern, or get the line at once when the log already has it.

log_wait(pattern, channel, seconds=30.0, since_mark=0)

Try it

On Gridlee, a free ROM from mamedev.org, after turning the throttle off and letting the game run five seconds.
Ask

Check MAME's log for the line that says the throttle went off.

Call
log_wait(pattern="MAME_MCP_THROTTLE#1", channel="emulator")
Reply 4 of 12 fields
{
  "summary": "log_wait emulator /MAME_MCP_THROTTLE#1/: matched already there",
  "verdict": "TARGET",
  "line": "[luaengine] MAME_MCP_THROTTLE#1 throttled=false frame=0",
  "already": true
}

TARGET means a line matched, and already that the log held it before the call, so nothing was waited for. The line is the one MAME wrote when the throttle went off.

The whole reply
JSON
{
  "summary": "log_wait emulator /MAME_MCP_THROTTLE#1/: matched already there",
  "status": "ok",
  "verdict": "TARGET",
  "pattern": "MAME_MCP_THROTTLE#1",
  "channel": "emulator",
  "line": "[luaengine] MAME_MCP_THROTTLE#1 throttled=false frame=0",
  "already": true,
  "lines_total": 1,
  "lines_before": 4,
  "arrived_during": 0,
  "waited_s": "<volatile>",
  "lines_examined": 6
}

Arguments

pattern string, required
A regular expression each line is searched for. It is never empty: . matches every line.
channel one of "emulator", "process", "all", required
Which log to wait on: emulator, process or all, as in log.
seconds number (> 0, <= 600.0), default 30.0
How long to wait at most, in seconds, up to 600. Left out, 30.
since_mark integer (>= 0), default 0
A byte position in the log: only lines written after it count, the ones already there included. Left out or 0, the whole log counts.

What comes back

verdict
TARGET when a line matched, TIMEOUT when the time ran out with none; note then says what was read.
line
The first line that matched; for the newest one, use log.
already
true when the log held the line before the call, so nothing was waited for.
waited_s
Seconds spent waiting; 0 when the line was already there.
arrived_during
How many lines were written during the wait, whether or not they matched.
lines_examined
How many lines were read in all: those the log held and those that came during the wait.
All 10 reply fields
  • already (boolean)
  • arrived_during (integer)
  • channel (string)
  • line (string)
  • lines_before (integer)
  • lines_examined (integer)
  • lines_total (integer)
  • pattern (string)
  • verdict (string)
  • waited_s (number)

What it refuses

Why it works this way

The log is read before any waiting, so a line written before the call is found at once, where a tool that only waited would report that it never came. already marks such a line.

A TIMEOUT says what it read. arrived_during counts the lines written during the wait and lines_examined every line read, so a program that wrote nothing is told apart from one whose lines did not match.

A stop during the wait is refused like a machine already stopped, after one last read of the log. After a TIMEOUT the program still runs. Progress is reported while it waits.

More on why

lines_before counts the lines read before the match and lines_total the matches in that read.

The contract your client receives
Text
Wait up to `seconds` for a line of `channel` matching the regex `pattern` (never empty);
at once if the log holds it. Answers while running. `channel`, `since_mark` as in `log`.

Refused: `wait_stopped` when stopped and the log lacks the line; `session_broken`; a bad
`seconds`, regex or `since_mark`.

Reply: `verdict` `TARGET`, `line` (the first match), `already`, `waited_s`, `lines_before`,
`lines_total`, `arrived_during`, `lines_examined`; on timeout `verdict` `TIMEOUT`, `note`.

Reference: REFERENCE.md, The log.
Tools