throttle
Choose whether the machine runs at real speed or as fast as the host can.
throttle(on, seconds=5.0)
Try it
Turn real-speed throttling off so the game fast-forwards, then confirm the switch was applied.
throttle(on=false){
"summary": "throttle off: pending until the console next reads a line",
"status": "ok",
"on": false,
"pending": true,
"tag": "MAME_MCP_THROTTLE#1"
}Then, once the game has run, look for the tag in MAME's log:
log_wait(pattern="MAME_MCP_THROTTLE#1", channel="emulator"){
"summary": "log_wait emulator /MAME_MCP_THROTTLE#1/: matched already there",
"status": "ok",
"verdict": "TARGET",
"line": "[luaengine] MAME_MCP_THROTTLE#1 throttled=false frame=0"
}pending means the switch waits for the machine to move, and tag is the text it writes to MAME's log once applied. The second call finds that line, throttled=false: TARGET means the pattern matched.
The two replies, whole
The first call's:
{
"summary": "throttle off: pending until the console next reads a line",
"status": "ok",
"on": false,
"pending": true,
"applies": "when the console next reads a line: a step, the next frame emulated, or a debugger command on a stub that refreshes after one",
"tag": "MAME_MCP_THROTTLE#1",
"confirmed_by": "its tag in the error log, read by the next stop's survey, by `status` and by `close`; `status` lists it in `throttles_pending` until then, and if the tag never comes, every reply after that says so in `session.throttles_not_applied`"
}The second call's:
{
"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
- on boolean, required
trueruns the machine at real speed;falsefast-forwards it, as fast as the host can.- seconds number (> 0, <= 600.0), default
5.0 - With the machine running, how long to wait for the switch to be confirmed, in real seconds, up to 600. Left out, 5.
What comes back
- pending
truewhen the switch is not applied yet: the machine is stopped, and the console runs the line when it next moves.falseonce applied.- tag
- The text the switch writes in MAME's log when it applies,
MAME_MCP_THROTTLE#n. Give it tolog_waiton theemulatorlog to wait for it. - on
- The setting asked for.
- frame
- The frame at which the switch applied, and
waited_show long that took. Only whenpendingisfalse. - applies
- For a switch not applied yet, when it takes effect;
confirmed_bysays which later replies confirm it.
All 8 reply fields
applies(string)confirmed_by(string)frame(integer)on(boolean)pending(boolean)tag(string)tagged_lines(array)waited_s(number)
What it refuses
- A switch not confirmed within
secondson a running machine: it is still waiting, andstatuslists it (wait_expired). - A machine that reports the other setting after the switch (
readback_refused).
Why it works this way
The switch is a line sent to MAME's console, and the console runs a line only when the machine moves. Asked on a stopped machine it cannot wait for its own confirmation, because nothing runs the line while it waits. The reply is pending, with the tag to look for.
So, stopped at a breakpoint, ask and then resume: the machine runs at the new speed from its first frame. A switch not applied yet is looked for again at the next stop, by status and by close. Until then status lists it in throttles_pending.
A switch that never took effect is not forgotten. When the console went past the line without applying it, or the machine reports the other setting, every later reply says so in session.throttles_not_applied, which stays set until close. Asking again fixes the speed and the record stays: this session measured at a speed nobody chose.
More on why
No call is refused over a switch that was not applied. The record is on every reply because the call that would report it is one nobody has to make. Until the console has gone past the line there is no record: the pending you were given is still true.
The console reads a line on a step, on the next frame emulated, or after a debugger command on a MAME build that refreshes after one. A machine that stops again before its next frame leaves the switch waiting.
The tag is text to search the log for, never a mark, which is a position in a log. Its number counts every line this session sent to the console, not the switches. log_wait takes a regular expression, so #1 also matches #10.
start's throttle_from_frame is the same switch decided at launch: fast-forward up to that frame, real speed after it.
tagged_lines, on a refusal, are the log lines that carry the tag.
Related tools
The contract your client receives
Switch real-speed throttling `on` or off; it applies when the console next reads a line.
Stopped, the reply is `pending: true` with a `tag` for `log_wait` on the `emulator`
channel. Running, it waits up to `seconds` for the tag; a bound that runs out is
`wait_expired`.
Reply: `on`, `pending`, `tag`; pending: `applies`, `confirmed_by`; applied: `frame`,
`waited_s`.
Reference: REFERENCE.md, Input and the screen.