docs/lib/Critical.htm

<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Critical - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The Critical statement prevents the current thread from being interrupted by other threads, or enables it to be interrupted." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Critical</h1>

<p>Prevents the <a href="../misc/Threads.htm">current thread</a> from being interrupted by other threads, or enables it to be interrupted.</p>

<pre class="Syntax">
<span class="func">Critical</span> <span class="optional">, OnOffNumeric</span>
</pre>

<h2 id="Parameters">Parameters</h2>
<dl>
  <dt>OnOffNumeric</dt>
  <dd>
    <p>If blank or omitted, it defaults to On. Otherwise, specify one of the following:</p>
    <p><strong>On</strong>: The <a href="../misc/Threads.htm">current thread</a> is made critical, meaning that it cannot be interrupted by another thread.</p>
    <p><strong>Off</strong>: The current thread immediately becomes interruptible, regardless of the settings of <a href="Thread.htm">Thread Interrupt</a>. See <a href="#Off">Critical Off</a> for details.</p>
    <p><strong>(Numeric)</strong> <span class="ver">[v1.0.47+]</span>: Specify a positive number to turn on Critical but also change the number of milliseconds between checks of the internal message queue. See <a href="#Interval">Message Check Interval</a> for details. <span class="ver">[v1.0.48+]</span>: Specifying 0 turns off Critical. Specifying -1 turns on Critical but disables message checks.</p>
  </dd>
</dl>

<h2 id="Behave">Behavior of Critical Threads</h2>
<p>Critical threads are <em>uninterruptible</em>; for details, see <a href="../misc/Threads.htm#Behave">Threads</a>.</p>
<p>A critical thread becomes interruptible when a <a href="MsgBox.htm">message box</a> or other dialog is displayed. However, unlike <a href="Thread.htm">Thread Interrupt</a>, the thread becomes critical again after the user dismisses the dialog.</p>

<h2 id="Off">Critical Off</h2>
<p>When buffered events are waiting to start new threads, using <code>Critical Off</code> will not result in an immediate interruption of the current thread. Instead, an average of 5 milliseconds will pass before an interruption occurs. This makes it more than 99.999% likely that at least one line after <code>Critical Off</code> will execute before an interruption. You can force interruptions to occur immediately by means of a delay such as a <code><a href="Sleep.htm">Sleep</a> -1</code> or a <a href="WinWait.htm">WinWait</a> for a window that does not yet exist.</p>
<p><code>Critical Off</code> cancels the current thread's period of uninterruptibility even if the thread was not Critical, thereby letting events such as <a href="Gui.htm#GuiSize">GuiSize</a> be processed sooner or more predictably.</p>

<h2 id="Settings">Thread Settings</h2>
<p>See <a href="../Variables.htm#IsCritical">A_IsCritical</a> for how to save and restore the current setting of Critical. However, since Critical is a thread-specific setting, when a critical thread ends, the underlying/resumed thread (if any) will  be automatically noncritical. Consequently there is no need to do <code>Critical Off</code> right before ending a thread.</p>
<p>If Critical is not used in the auto-execute section (top part of the script), all threads start off as noncritical (though the settings of <a href="Thread.htm">Thread Interrupt</a> will still apply). By contrast, if the auto-execute section turns on Critical but never turns it off, every newly launched <a href="../misc/Threads.htm">thread</a> (such as a <a href="../Hotkeys.htm">hotkey</a>, <a href="Menu.htm">custom menu item</a>, or <a href="SetTimer.htm">timed</a> subroutine) starts off critical.</p>
<p>The command <a href="Thread.htm">Thread NoTimers</a> is similar to Critical except that it only prevents interruptions from <a href="SetTimer.htm">timers</a>.</p>
<p><span class="ver">[v1.0.47+]</span>: Turning on Critical also puts <code><a href="SetBatchLines.htm">SetBatchLines</a> -1</code> into effect for the <a href="../misc/Threads.htm">current thread</a>.</p>

<h2 id="Interval">Message Check Interval</h2>
<p><span class="ver">[v1.0.47+]</span>: Specifying a positive number as the first parameter (e.g. <code>Critical 30</code>) turns on Critical but also changes the minimum number of milliseconds between checks of the internal message queue. If unspecified, the default is 16 milliseconds while Critical is On, and 5 ms while Critical is Off. Increasing the interval postpones the arrival of messages/events, which gives the <a href="../misc/Threads.htm">current thread</a> more time to finish. This reduces the possibility that certain <a href="OnMessage.htm">OnMessage()</a> and <a href="Gui.htm#DefaultWin">GUI events</a> will be lost due to "thread already running". However, commands that wait such as <a href="Sleep.htm">Sleep</a> and <a href="WinWait.htm">WinWait</a> will check messages regardless of this setting (a workaround is <code>DllCall("Sleep", "UInt", 500)</code>).</p>
<p>This setting affects the following:</p>
<ul>
  <li>Preemptive message checks, which potentially occur before each line of code executes.</li>
  <li>Periodic message checks during <a href="Send.htm">Send</a>, file and download operations.</li>
</ul>
<p>It does not affect the frequency of message checks while the script is paused or waiting.</p>
<p>Because the system tick count generally has a granularity of 15.6 milliseconds, the minimum delta value is generally at least 15 or 16. The duration since the last check must <em>exceed</em> the interval setting in order for another check to occur. For example, a setting of 16 requires the tick count to change by 17 or greater. As a message check could occur at any time within the 15.6 millisecond window, any setting between 1 and 16 could permit two message checks within a single interval.</p>
  <p class="note"><strong>Note</strong>: Increasing the message-check interval too much may reduce the responsiveness of various events such as <a href="Gui.htm">GUI</a> window repainting.</p>
<p><code>Critical -1</code> turns on Critical but disables message checks. This does not prevent the program from checking for messages while performing a sleep, delay or wait. It is useful in cases where dispatching messages could interfere with the code currently executing, such as while handling certain types of messages during an <a href="OnMessage.htm">OnMessage</a> callback.</p>

<h2 id="Related">Related</h2>
<p><a href="Thread.htm">Thread (command)</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="_MaxThreadsPerHotkey.htm">#MaxThreadsPerHotkey</a>, <a href="_MaxThreadsBuffer.htm">#MaxThreadsBuffer</a>, <a href="OnMessage.htm">OnMessage()</a>, <a href="RegisterCallback.htm">RegisterCallback()</a>, <a href="Hotkey.htm">Hotkey</a>, <a href="Menu.htm">Menu</a>, <a href="SetTimer.htm">SetTimer</a></p>

<h2 id="Examples">Examples</h2>
<div class="ex" id="ExBasic">
<p><a class="ex_number" href="#ExBasic"></a> Press a hotkey to display a tooltip for 3 seconds. Due to Critical, any new thread that is launched during this time (e.g. by pressing the hotkey again) will be postponed until the tooltip disappears.</p>
<pre>#space::  <em>; Win+Space hotkey.</em>
Critical
ToolTip No new threads will launch until after this ToolTip disappears.
Sleep 3000
ToolTip  <em>; Turn off the tip.</em>
return  <em>; Returning from a hotkey subroutine ends the thread. Any underlying thread to be resumed is noncritical by definition.</em></pre>
</div>

</body>
</html>