SCRYDOSBox-XReferenceMachinelog_waitAlso in MAME

DOSBox-XMachine

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 Bricks, the game this repository builds, started with logfile and running, a ball served and nobody at the paddle.
Ask

Wait up to a minute for the game to log that the ball was lost.

Call
log_wait(pattern="LOST$", channel="guest", seconds=60)
Reply 4 of 12 fields
{
  "verdict": "TARGET",
  "pattern": "LOST$",
  "channel": "guest",
  "line": "Bochs port E9h: LOST"
}

TARGET means a line matched within the minute: the game logged LOST, a line of its own, written to port 0xE9.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "verdict": "TARGET",
  "pattern": "LOST$",
  "channel": "guest",
  "line": "Bochs port E9h: LOST",
  "already": "<volatile>",
  "lines_total": "<volatile>",
  "lines_before": "<volatile>",
  "arrived_during": "<volatile>",
  "waited_s": "<volatile>",
  "lines_examined": "<volatile>"
}

Arguments

pattern string, required
A regular expression each line is searched for. It is never empty: . matches every line.
channel one of "guest", "emulator", "all", "dos", required
Which log to wait on: guest, emulator, all or dos, 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. On dos, call holds the matching call in its place.
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. On dos, the calls the server holds.
All 12 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)
  • call (object)
  • calls_dropped (integer)

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 log that does not exist yet is not refused: that is the state right after resume. When the wait returns the program is usually still running: use the line to choose an address for run_to or watch_add on the next run.

More on why
  • lines_before counts the lines read before the match and lines_total the matches in that read. On dos both count calls, and calls_dropped the oldest ones the server let go.
  • A debugger that does not answer, inside a long host call, is asked once, and then only the file is read. A TIMEOUT says the run state is unknown.
  • No breakpoint can be set on a log line; the nearest is a watch for changes on the variable whose change produces it.
  • expect on send_keys and drive is this wait on guest, from a position taken before the keys are sent.
The contract your client receives
Text
When a line of `channel` matching `pattern` was logged: at once if the log already holds it,
else wait up to `seconds`. `channel` and `since_mark` as in `log`. Works on a running guest.

Reply: `verdict` `TARGET`, `pattern`, `channel`, `line` (the first match, not on `dos`),
`call` (on `dos`), `already`, `waited_s`, `lines_before`, `lines_total`, `arrived_during`,
`lines_examined` (the calls held on `dos`), `calls_dropped` (on `dos`, past the calls held);
on timeout `verdict` `TIMEOUT`
with `note`, `arrived_during`, `lines_examined`, `waited_s`. `status: INVALID`: `wait_stopped`
on a stopped machine whose
log lacks the line, `session_broken` when the emulator went away; no `logfile`, a bad
`seconds`, regex, channel or `since_mark` are refused.

Reference: REFERENCE.md, The log.
Tools