Skip to content

Commit a0d36e9

Browse files
MattDodsonEnglishPerlence
authored andcommitted
Edits "Advanced" docs.
I simplified some of the wording about multi-threading, and rearranged a paragraph to make sure important info doesn't get burried.
1 parent c0246b8 commit a0d36e9

File tree

1 file changed

+21
-19
lines changed

1 file changed

+21
-19
lines changed

docs/advanced.rst

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Advanced Usage
22
==============
33

4-
This document covers some of AutoHotkey.py more advanced features.
4+
This document covers some of AutoHotkey.py's more advanced features.
55

66

77
.. index::
@@ -10,29 +10,31 @@ This document covers some of AutoHotkey.py more advanced features.
1010
Threading
1111
---------
1212

13-
In Python, the :mod:`threading` module can be used to improve the responsiveness
14-
of applications that accept user input while other tasks run in the background.
15-
A related use case is running I/O in parallel with computations in another
16-
thread. These are actual OS threads, as opposed to AHK `pseudo-threads
13+
In Python, the :mod:`threading` module can improve the responsiveness
14+
of applications that accept user input while other tasks are running in the
15+
background. A related use case is running I/O in parallel with computations in
16+
another thread. These are actual OS threads, as opposed to AHK `pseudo-threads
1717
<https://www.autohotkey.com/docs/misc/Threads.htm>`_.
1818

19-
Calling AHK functions from Python is implemented in AutoHotkey.py by registering
20-
a callback in AHK with `RegisterCallback
19+
AutoHotkey.py calls AHK functions from python by registering a callback in AHK
20+
with `RegisterCallback
2121
<https://www.autohotkey.com/docs/commands/RegisterCallback.htm>`_. *These
22-
callbacks are not thread-safe.* That is, while the *main thread* is busy
23-
executing an AHK function, trying to call another AHK function from *another
24-
thread* leads to unpredictable results like program crash.
22+
callbacks are not thread-safe.* That is, while the *main thread* is busy executing
23+
an AHK function, calling another AHK
24+
function from *another thread* yields unpredictable results. It may even crash
25+
the program.
2526

26-
Thus, the *global AutoHotkey lock* (GAL) was introduced. It ensures that only
27+
Thus, the *global AutoHotkey lock* (GAL) was introduced. GAL ensures that only
2728
one OS thread interacts with AHK at a time.
2829

29-
In order for background threads to work, the main thread must also be crunching
30+
For background threads to work, the main thread must also be crunching
3031
Python code, for example, actively waiting for the background threads to finish.
31-
However, calling :meth:`threading.Thread.join` in the main thread will block the
32-
handling of the AHK message queue. That is, AHK won't be able to handle the
33-
hotkeys and other callbacks. Instead, let AHK handle its message queue by
34-
calling :func:`ahkpy.sleep` repeatedly while checking that the background thread
35-
is alive::
32+
However, calling :meth:`threading.Thread.join` in the main thread blocks AHK
33+
message queue handling. In such cases, AHK cannot handle hotkeys and other
34+
callbacks.
35+
36+
Instead, let AHK handle its message queue by calling :func:`ahkpy.sleep`
37+
repeatedly while checking that the background thread is alive::
3638

3739
import threading
3840
th = threading.Thread(target=some_worker)
@@ -45,8 +47,8 @@ asyncio
4547
-------
4648

4749
AutoHotkey.py works well with :mod:`asyncio`. When starting a long-running loop,
48-
schedule the :func:`ahkpy.sleep` call repeatedly, so it could give time to AHK
49-
to process its message queue::
50+
schedule the :func:`ahkpy.sleep` call repeatedly. This gives AHK time to
51+
process its message queue::
5052

5153
import asyncio
5254

0 commit comments

Comments
 (0)