@@ -8,13 +8,24 @@ One consequence is that a package that launches
88` Task ` s in its ` __init__ ` function may precompile successfully,
99but block precompilation of any packages that depend on it.
1010
11+ The symptom of this problem is a message
12+ ```
13+ ◐ MyPackage: Waiting for background task / IO / timer. Interrupt to inspect...
14+ ```
15+ that may appear during precompilation, with that precompilation process
16+ "hanging" until you press Ctrl-C.
17+
18+ Aqua has checks to determine whether your package * causes* this problem.
19+ Conversely, if you're a * victim* of this problem, it also has tools to help you
20+ determine which of your dependencies is causing the problem.
21+
1122## Example
1223
1324Let's create a dummy package, ` PkgA ` , that launches a persistent ` Task ` :
1425
1526``` julia
1627module PkgA
17- const t = Ref {Any } () # to prevent the Timer from being garbage-collected
28+ const t = Ref {Timer } () # used to prevent the Timer from being garbage-collected
1829__init__ () = t[] = Timer (0.1 ; interval= 1 ) # create a persistent `Timer` `Task`
1930end
2031```
@@ -32,16 +43,31 @@ fails to precompile: `using PkgA` runs `PkgA.__init__()`, which
3243leaves the ` Timer ` ` Task ` running, and that causes precompilation
3344of ` PkgB ` to hang.
3445
35- ## Example with ` expr `
46+ Without Aqua's tests, the developers of ` PkgA ` might not realize that their
47+ package is essentially unusable with any other package.
48+
49+ ## Checking for persistent tasks
50+
51+ Running all of Aqua's tests will automatically check whether your package falls
52+ into this trap. In addition, there are ways to manually run (or tweak) this
53+ specific test.
54+
55+ ### Manually running the peristent-tasks check
3656
37- You can test that an expression using your package finishes without leaving any persistent
38- tasks by passing a quoted expression:
57+ [ ` Aqua.test_persistent_tasks(MyPackage) ` ] ( @ref ) will check whether ` MyPackage ` blocks
58+ precompilation for any packages that depend on it.
59+
60+ ### Using an ` expr ` to check more than just ` __init__ `
61+
62+ By default, ` Aqua.test_persistent_tasks ` only checks whether a package's
63+ ` __init__ ` function leaves persistent tasks running. To check whether other
64+ package functions leave persistent tasks running, pass a quoted expression:
3965
4066``` julia
4167Aqua. test_persistent_tasks (MyPackage, quote
4268 # Code to run after loading MyPackage
4369 server = MyPackage. start_server ()
44- MyPackage. stop_server! (server)
70+ MyPackage. stop_server! (server) # ideally, this this should cleanly shut everything down. Does it?
4571end )
4672```
4773
@@ -76,8 +102,38 @@ function __init__()
76102end
77103```
78104
79- In more complex cases, you may need to set up independently-callable functions
80- to launch the tasks and set conditions that allow them to cleanly exit.
105+ In more complex cases, you may need to modify the task to support a clean
106+ shutdown. For example, if you have a ` Task ` that runs a never-terminating
107+ ` while ` loop, you could change
108+
109+ ```
110+ while true
111+ ⋮
112+ end
113+ ```
114+
115+ to
116+
117+ ```
118+ while task_should_run[]
119+ ⋮
120+ end
121+ ```
122+
123+ where
124+
125+ ```
126+ const task_should_run = Ref(true)
127+ ```
128+
129+ is a global constant in your module. Setting ` task_should_run[] = false ` from
130+ outside that ` while ` loop will cause it to terminate on its next iteration,
131+ allowing the ` Task ` to finish.
132+
133+ ## Additional information
134+
135+ [ Julia's devdocs] ( https://docs.julialang.org/en/v1/devdocs/precompile_hang/ )
136+ also discuss this issue.
81137
82138## [ Test functions] (@id test_persistent_tasks)
83139
0 commit comments