SCRYMAMEReferenceSessioncloseAlso in DOSBox-X
close
End the session and the emulator with it, and learn how it ended.
close(detail=false)
Try it
We are done: close the emulator and tell me how it ended.
close(){
"summary": "close: quit, exit code 0, last words left out (see `omitted`)",
"status": "ok",
"closed": true,
"ended_by": "quit",
"exit_code": 0,
"cfg_written": true,
"draft": ["maps/gridlee", "perform/two-coins", "start/gridlee"]
}MAME quit when asked, with exit code 0, and wrote its cfg. draft names three things the session saved that promote can still write into a repository's .scry/ folder.
The whole reply
{
"summary": "close: quit, exit code 0, last words left out (see `omitted`)",
"status": "ok",
"closed": true,
"omitted": ["stdout_tail", "errorlog_tail"],
"how": "close(detail=True) keeps the channels' last words on a clean quit too; once a close has answered they are gone with the scratch",
"ended_by": "quit",
"exit_code": 0,
"cfg_written": true,
"cfg": {"available": false, "why": "no cfg was given, so MAME runs on its defaults"},
"console_pending_before": 0,
"console_drained": 0,
"draft": ["maps/gridlee", "perform/two-coins", "start/gridlee"]
}Arguments
- detail boolean, default
false truereturns the last lines the emulator printed (stdout_tail,errorlog_tail) after a clean quit too. Left out, they come only when the end was not clean.
What comes back
- closed
truewhen a session was ended;falsewhen there was none to close.- ended_by
- How it ended:
quit,exited,killed,diedornone. - exit_code
- The emulator's exit code. It is
available: falsewith awhywhen no session was running or the killed process could not be collected. - average_speed
- The emulation speed over the last run
resumeopened, aspercent. Absent when no such run was open. - cfg
- With a
cfgatstart:installed_path, andchanged, whether MAME rewrote the installed copy. - draft
- The names of what the session saved and
promotehas not yet written into your repository's.scry/folder.
All 10 reply fields
draft(array of string)average_speed(object)cfg(object)closed(boolean)console_drained(integer)console_pending_before(integer)ended_by(string)errorlog_tail(string)cfg_written(boolean or object)stdout_tail(string)
Why it works this way
close asks MAME to quit through its console and kills it only when it has not gone within the grace period. MAME writes cfg/ and nvram/ on a clean exit only, and ignores SIGTERM. ended_by says which happened, since closed: true would say the same of every ending.
It is the one way out of every state: it works on a running machine and on a broken session, and with no session it answers closed: false. The session's temporary folder is deleted; a state_dir you named stays.
session describes the state after the close: alive, running and altered are false, as with no session. A doubt about what the session reported, a console error count or a speed switch that never applied, is still there, because it stays true of the answers you have.
More on why
-
quit: a clean exit.cfg_writtensays whether MAME wrote its cfg, and is unavailable when there was no cfg file to read. -
exited: it exited and wrote none. -
killed: killed after the grace period.exit_codeis unavailable if the process is still not collected. -
died: it had already exited. -
none: there was no session. -
average_speedis the server's own measure, the debugger's emulated clock over the wall clock: MAME prints no speed line when it exits from the debugger. -
It holds
percentand the two deltas, oravailable: falsewith awhy. -
Lua lines still waiting in the console are run before the quit, because one left there can crash MAME on its way out.
console_pending_beforeandconsole_drainedcount them. -
The
notenames the lines that could not be run, so a bad exit code has its likely cause beside it. -
cfgis unavailable when no cfg was given, andchangedsays so when the copy could not be read back. -
When the last lines are left out,
omittednames them andhowsays what brings them. -
On a broken session
closeasks MAME nothing: no drain, no speed read and noquit, only the kill. -
The last lines are read before the temporary folder is deleted, so a MAME that died still gives its last words in
stdout_tailanderrorlog_tail.
Related tools
The contract your client receives
End the session: MAME is asked to `quit` and killed only if it has not gone within the
grace period. The scratch is deleted; a named `state_dir` stays. Works on a running machine;
with no session it answers `closed: false`.
Reply: `closed`, `ended_by` (`quit`, `exited`, `killed`, `died`, `none`), `exit_code` (an
integer, or unavailable with its `why` when no session was running or the process was not
reaped), `cfg_written` (MAME wrote its cfg as it quit),
`cfg` (`installed_path`, `changed`), `average_speed` (while a `resume` run was open), `note`;
`stdout_tail` and `errorlog_tail` when the end was not a clean `quit`, or with `detail=True`.
`session` is the block as it is after the close (`alive` and `running` false); a console doubt
or a throttle found not applied still rides there, and `draft` names the candidates the
session left waiting for `promote`.
Reference: REFERENCE.md, The session.