SCRYDOSBox-XReferenceMachinelog_waitAlso in MAME
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
logfile and running, a ball served and nobody at the paddle.Wait up to a minute for the game to log that the ball was lost.
log_wait(pattern="LOST$", channel="guest", seconds=60){
"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
{
"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,allordos, 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. Ondos,callholds the matching call in its place. - 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. 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
- A machine stopped at the debugger, or one that stops during the wait, while the log lacks the line. It logs nothing, and
last_stopsays where it stopped (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).- A session started without
logfile(no_channel). doson a session not started withdos_calls(no_channel).doswith asince_mark(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 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_beforecounts the lines read before the match andlines_totalthe matches in that read. Ondosboth count calls, andcalls_droppedthe 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
TIMEOUTsays 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.
expectonsend_keysanddriveis this wait onguest, from a position taken before the keys are sent.
Related tools
The contract your client receives
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.