Needs docs on module initialization

[timholy]

The README doesn't describe how to handle ParallelStencil's initialization requirements. It should mention that each dependent package needs a __init__() function that calls @init_parallel_stencil, otherwise folks may try to call it from top-level in their module. xref timholy/Revise.jl#821

Alternatively (and better), you could switch to storing all the needed settings in the dependent module, e.g., have @init_parallel_stencil create a global const __parallel_stencil_initialized__ = true in the downstream package. It would also have to store any needed settings as well, of course. That would be precompile-friendly. The reason this is better is that (1) users don't need to know anything about __init__ functions, and (2) __init__ functions are awful black-boxes when it comes to the upcoming ability to compile small binaries (we will have to cache them regardless of whether they are needed). So it should be a win-win to move your storage into the dependent package.

[omlins]

@timholy Thanks a lot for opening this issue. Yes, moving the storage into the dependent module is definitely the better way to ensure compatibility with to revise.

[timholy]

Not just Revise. It's really a package precompilation issue: currently, any "work" that needs to be done to initialize ParallelStencil must be done from within an __init__ function in the dependent package, otherwise that work is done ephemerally only when the package is precompiled. Since the "results" are not saved in ParallelStencil's precompilation cache, things will just break.

[omlins]

@timholy: similar observations as you made with revise.jl can be made with pluto.jl, as a newly opened issue just showed: #178 . Naturally, I would like to do a fix that resolves both issues. Would you mind having a quick look at what was reported? Do you think storing all the needed settings in the dependent module should also solve the pluto issue?

Alternatively (and better), you could switch to storing all the needed settings in the dependent module, e.g., have @init_parallel_stencil create a global const parallel_stencil_initialized = true in the downstream package.

Thanks a lot for your suggestion. Instead of creating global constants for each setting in the caller module, I would prefer to create a single metadata submodule in the caller module bundling all the settings. Do you see any issues with this solution?

[omlins]

Instead of creating global constants for each setting in the caller module, I would prefer to create a single metadata submodule in the caller module bundling all the settings.

@timholy This worked out without any issues and we have now full compatibility with Revise.jl. Thanks for the hint!
A side note: we did not have any problems is pre-compilation in general (we have unit tests to ensure that incremental precompilation as well as usage of extensions works).

[timholy]

Glad you're fixing things successfully. Since you asked, let me explain the precompilation issue a bit more. First, navigate to a temporary directory (here I'll call it /tmp/modinit), launch julia, and then run this code:

using Pkg
Pkg.generate("MyPkg")
Pkg.generate("UserPkg")
Pkg.activate("UserPkg")
Pkg.develop(PackageSpec(path=abspath("MyPkg")))
write("MyPkg/src/MyPkg.jl", """
module MyPkg
const nusers = Ref(0)
end
""")
write("UserPkg/src/UserPkg.jl", """
module UserPkg
using MyPkg
MyPkg.nusers[] += 1
@show MyPkg.nusers[]
end
""")

Briefly, this creates two packages, MyPkg and UserPkg. UserPkg loads MyPkg and increments MyPkg's nusers counter, "registering" itself as a user of MyPkg.

The following might surprise you:

tim@diva:/tmp/modinit$ julia -q --startup=no --project=UserPkg
julia> using UserPkg
Precompiling UserPkg
        Info Given UserPkg was explicitly requested, output will be shown live
MyPkg.nusers[] = 1
  2 dependencies successfully precompiled in 3 seconds
  1 dependency had output during precompilation:
┌ UserPkg
│  [Output was shown above]
└

julia> UserPkg.MyPkg.nusers[]
0

Huh? How is nusers 0, when we showed that it was 1 when UserPkg was precompiled? If you run julia without precompiled packages, you'll get more of the behavior you might expect:

tim@diva:/tmp/modinit$ julia --compiled-modules=no -q --startup=no --project=UserPkg
julia> using UserPkg
MyPkg.nusers[] = 1

julia> UserPkg.MyPkg.nusers[]
1

The explanation is the following: precompilation stores a snapshot of the result of executing the package's main *.jl file. When you load a package, you're loading that snapshot, you're not re-executing the code. So:

• when you precompile MyPkg, you're starting a fresh Julia session, executing src/MyPkg.jl, saving the result to the cache file, and quitting the Julia session. The precompiled cache file for MyPkg stores nusers[] = 0 in its snapshot, because you never loaded UserPkg while precompiling MyPkg.
• when UserPkg is precompiled, it launches a fresh Julia session, loads the cache file for MyPkg, and executes src/UserPkg.jl. This increments nusers for the in-memory copy for this session. When it saves the cache file for UserPkg, it does not update the cache file for MyPkg. This Julia session also exits.
• in your main process, you just load the two cache files. Since nusers[] = 0 in the MyPkg cache file, this is what you get.

"Fixing" this is what __init__ functions are for. But they are an awful hack and should be avoided whenever possible. If all needed data are instead stored in UserPkg, those data are saved when the precompile cache for UserPkg gets written. Problem solved.