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.