Sets the priority or interruptibility of threads. It can also temporarily disable all timers.
Thread SubFunction , Value1, Value2
The SubFunction, Value1, and Value2 parameters are dependent upon each other and their usage is described below.
Thread is also the class describing one thread. The current thread is A_Thread; see Thread Object below.
For SubFunction, specify one of the following:
Prevents interruptions from any timers.
Thread "NoTimers" , False
This sub-function prevents interruptions from any timers until the current thread either ends, executes Thread "NoTimers", false, or is interrupted by another thread that allows timers (in which case timers can interrupt the interrupting thread until it finishes).
If this setting is not changed by the auto-execute thread, all threads start off as interruptible by timers (though the settings of the Interrupt sub-function described below will still apply). By contrast, if the auto-execute thread turns on this setting but never turns it off, every newly launched thread (such as a hotkey, custom menu item, or timer) starts off immune to interruptions by timers.
Regardless of the default setting, timers will always operate when the script has no threads (unless Pause has been turned on).
Thread "NoTimers" is equivalent to Thread "NoTimers", true. In addition, since the False parameter is an expression, true resolves to 1, and false to 0. See Boolean Values for details.
Changes the priority level of the current thread.
Thread "Priority", Level
Specify for Level an integer between -2147483648 and 2147483647 (or an expression) to indicate the current thread's new priority. This has no effect on other threads. See Threads for details.
Due to its ability to buffer events, the function Critical is generally superior to this sub-function.
On a related note, the OS's priority level for the entire script can be changed via ProcessSetPriority. For example:
ProcessSetPriority "High"
Changes the duration of interruptibility for newly launched threads.
Thread "Interrupt" , Duration, LineCount
Note: LineCount is accepted but ignored; interruptibility is controlled by Duration alone.
Note: This sub-function should be used sparingly because most scripts perform more consistently with settings close to the defaults.
By default, every newly launched thread is uninterruptible for a Duration of 17 milliseconds or a LineCount of 1000 script lines, whichever comes first. This gives the thread a chance to finish rather than being immediately interrupted by another thread that is waiting to launch (such as a buffered hotkey or a series of timed subroutines that are all due to be run).
Note: Any Duration less than 17 might result in a shorter actual duration or immediate interruption, since the system tick count has a minimum resolution of 10 to 16 milliseconds. However, at least one line will execute before the thread becomes interruptible, allowing the script to enable Critical, if needed.
If either parameter is 0, each newly launched thread is immediately interruptible. If either parameter is -1, the thread cannot be interrupted as a result of that parameter. The maximum for both parameters is 2147483647.
This setting is global, meaning that it affects all subsequent threads, even if this function was not called by the auto-execute thread. However, interrupted threads are unaffected because their period of uninterruptibility has already expired. Similarly, the current thread is unaffected except if it is uninterruptible at the time the LineCount parameter is changed, in which case the new LineCount will be in effect for it.
If a hotkey is pressed or a custom menu item is selected while the current thread is uninterruptible, that event will be buffered. In other words, it will launch when the current thread finishes or becomes interruptible, whichever comes first. The exception to this is when the current thread becomes interruptible before it finishes, and it is of higher priority than the buffered event; in this case the buffered event is unbuffered and discarded.
Regardless of this sub-function, a thread will become interruptible the moment it displays a MsgBox, InputBox, FileSelect, or DirSelect dialog.
Either parameter can be left blank to avoid changing it.
class Thread extends Object
Describes one thread — the cooperative unit a hotkey, timer, GUI event or the auto-execute section runs in. This is distinct from a RealThread, which is a real operating-system thread.
Thread objects are not constructed; calling Thread runs the sub-functions above. Obtain one from A_Thread, from Underlying, or from RealThread.Threads.
#Import "Ks" { A_Thread }
MsgBox "This thread has run for " A_Thread.Elapsed " ms"
Type: Integer
An identifier which is unique for the script's lifetime in practice, but only meaningful while the thread is active.
A real thread which is not running any script thread — a worker idling in its event loop, or a thread the runtime adopted — still answers A_Thread, with an Id of 0. That value identifies no thread and is not unique between real threads.
Type: Integer
The one-based position of this thread in its real thread's stack. 1 is the oldest active thread, matching A_RealThread.Threads[1]. The auto-execute thread is index 1 on the main thread.
Type: Boolean
True while this thread is still running. See Object lifetime.
Type: String
What launched this thread, or an empty string when the launch site does not name one:
| Kind | Launched by |
|---|---|
Auto | The auto-execute section. |
Hotkey | A hotkey. |
Hotstring | A hotstring. |
Timer | SetTimer. |
Event | A registered handler or event hook: GUI events, menu items, OnExit, OnClipboardChange, Monitor.OnChange, Clipboard.OnChange and Audio.OnDeviceChange hooks, and Overlay pointer handlers (OnEvent). |
Message | OnMessage. |
Callback | A CallbackCreate pointer invoked from native code. |
Input | An InputHook event. |
WinEvent | A WinEvent subscription. |
Com | A COM event sink (ComObjConnect). |
Clr | A CLR event subscription. |
RealThread | A RealThread body, or work posted or sent to one. |
Type: Integer
Milliseconds elapsed since this thread was launched.
Type: Boolean
Whether timers may run in this thread. Can be read and set; setting it is the object form of the NoTimers sub-function, which sets the inverse. Accepts On and Off as well as a Boolean. Defaults to true.
Type: Integer
This thread's priority. Can be read and set, and reads back what the Priority sub-function set. Every thread starts at 0 unless its launcher gave it one.
Type: Boolean
Whether this thread is critical, that is, cannot be interrupted. Can be read and set; setting it is equivalent to Critical on that thread.
Type: Boolean
Whether this thread is paused. Can be read and set; setting it takes effect when that thread next resumes, which is the same flag Pause 1 sets. A_IsPaused is this property on Underlying.
Type: Boolean
Read-only. Whether this thread can currently be interrupted by a new one. False during the startup window set by the Interrupt sub-function and for the whole life of a critical thread.
Type: Thread or String
The thread this one interrupted, or an empty string when this is the oldest thread on its real thread.
The code which Exit or the Exit method ended this thread with. It is set as the exit takes effect and the thread begins to unwind, and is readable from any thread from then on, including after the thread has ended. It is an empty string before that, and for a thread which ended another way, such as by returning.
ThreadId := ThreadObj.Exit(ExitCode)
Requests that this thread exit, and returns its Id. ExitCode defaults to 0. It becomes this thread's ExitCode, and the process exit code as Exit describes.
The current thread exits immediately, so a call on it does not return. Any other thread is marked and unwinds when it next resumes and processes events; this is cooperative and does not asynchronously abort running code. A later request replaces a pending exit code. Exit is the equivalent for the current thread.
Exactly one object exists per thread, so == answers whether a thread is the one the calling code is in:
#Import "Ks" { A_Thread }
if thr == A_Thread
MsgBox "this is the running thread"
A Thread object describes only the thread it was made for. Once that thread ends, Id, Index and ExitCode keep answering from the captured values and IsActive reports 0, but every other property or method throws TargetError.
#Import "Ks" { A_Thread }
global captured := 0
SetTimer(() => captured := A_Thread, -1)
Sleep 100
MsgBox captured.IsActive ; 0 — the timer thread has ended
captured.Exit() ; throws TargetError
A thread stack belongs to one real thread. An object may be read from any real thread, but every setter and Exit throw TargetError when called from a different one.
Due to its greater flexibility and its ability to buffer events, the function Critical is generally more useful than Thread "Interrupt" and Thread "Priority".
Critical, Threads, RealThread, Exit, Hotkey, Menu object, SetTimer, Process functions