SCRYMAMEReferenceMachinelog_waitAlso in DOSBox-X
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
Check MAME's log for the line that says the throttle went off.
log_wait(pattern="MAME_MCP_THROTTLE#1", channel="emulator"){
"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
{
"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,processorall, as inlog. - 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
TARGETwhen a line matched,TIMEOUTwhen the time ran out with none;notethen says what was read.- line
- The first line that matched; for the newest one, use
log. - already
truewhen 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
- A machine stopped at the debugger, or one that stops during the wait, while the log lacks the line: a stopped machine logs nothing (
wait_stopped). - An emulator that exits during the wait (
session_broken). secondsout of range, an empty or malformed pattern, or asince_markpast the end of the log (bad_argument).
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.
Related tools
The contract your client receives
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.