SCRYMAMEReferenceSessioncloseAlso in DOSBox-X

MAMESession

close

End the session and the emulator with it, and learn how it ended.

close(detail=false)

Try it

On Gridlee, at the end of the example session, after it saved a screen map and a list of steps.
Ask

We are done: close the emulator and tell me how it ended.

Call
close()
Reply 7 of 12 fields
{
  "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
JSON
{
  "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
true returns 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
true when a session was ended; false when there was none to close.
ended_by
How it ended: quit, exited, killed, died or none.
exit_code
The emulator's exit code. It is available: false with a why when no session was running or the killed process could not be collected.
average_speed
The emulation speed over the last run resume opened, as percent. Absent when no such run was open.
cfg
With a cfg at start: installed_path, and changed, whether MAME rewrote the installed copy.
draft
The names of what the session saved and promote has 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_written says 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_code is unavailable if the process is still not collected.

  • died: it had already exited.

  • none: there was no session.

  • average_speed is 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 percent and the two deltas, or available: false with a why.

  • 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_before and console_drained count them.

  • The note names the lines that could not be run, so a bad exit code has its likely cause beside it.

  • cfg is unavailable when no cfg was given, and changed says so when the copy could not be read back.

  • When the last lines are left out, omitted names them and how says what brings them.

  • On a broken session close asks MAME nothing: no drain, no speed read and no quit, 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_tail and errorlog_tail.

The contract your client receives
Text
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.
Tools