Method ChangePauseState

source/script.cpp:12481–12513

ResultType Line::ChangePauseState(LPTSTR aChangeTo)
// Currently designed to be called only by the Pause command (ACT_PAUSE).
// Returns OK or FAIL.
{
	auto toggle = Convert10Toggle(ARG1);
	switch (toggle)
	{
	case NEUTRAL:
		return PauseCurrentThread();
	case TOGGLE:
		// Update for v2: "Pause -1" is more useful if it always applies to the thread immediately beneath
		// the current thread, since pausing the current thread would prevent a hotkey from unpausing itself
		// by default (there's no longer a special case allowing Pause hotkeys a second thread).
		if (g > g_array && g[-1].IsPaused) // Checking g>g_array avoids any chance of underflow, which might otherwise happen if this is called by the AutoExec section or a threadless callback running in thread #0.
			toggle = TOGGLED_OFF;
		// Fall through:
	case TOGGLED_ON:
	case TOGGLED_OFF:
		// v1.0.37.06: The old method was to unpause the the nearest paused thread on the call stack;
		// but it was flawed because if the thread that made the flag true is interrupted, and the new
		// thread is paused via the pause command, and that thread is then interrupted, when the paused
		// thread resumes it would automatically and wrongly be unpaused (i.e. the unpause ticket would
		// be used at a level higher in the call stack than intended).
		// Flag this thread so that when it ends, the thread beneath it will be unpaused.  If that thread
		// (which can be the idle thread) isn't paused the following flag-change will be ignored at a later
		// stage. This method also relies on the fact that the current thread cannot itself be paused right
		// now because it is what got us here.
		PauseUnderlyingThread(toggle != TOGGLED_OFF); // i.e. pause if ON or fell through from TOGGLE.
		return OK;
	default: // TOGGLE_INVALID or some other disallowed value.
		return LineError(ERR_PARAM1_INVALID, FAIL_OR_OK, aChangeTo);
	}
}