16 KiB
Module Instantiations and Visits
Modules often contain just function and structure-type definitions, in which case the module itself behaves in a purely functional way, and the time when the functions are created is not observable. If a module’s top-level expressions include side effects, however, then the timing of the effects can matter. The distinction between module declaration and instantiation provides some control over that timing. The concept of module visits further explains the interaction of effects with macro implementations.
1. Declaration versus Instantiation
Declaring a module does not immediately evaluate expressions in the module’s body. For example, evaluating
> (module number-n racket/base
(provide n)
(define n (random 10))
(printf "picked ~a\n" n))
declares the module number-n
, but it doesn’t immediately pick a random
number for n
or display the number. A require
of number-n
causes
the module to be instantiated (i.e., it triggers an
instantiation), which implies that the expressions in the body of the
module are evaluated:
> (require 'number-n)
picked 5
> n
5
After a module is instantiated in a particular namespace, further
require
s of the module use the same instance, as opposed to
instantiating the module again:
> (require 'number-n)
> n
5
> (module use-n racket/base
(require 'number-n)
(printf "still ~a\n" n))
> (require 'use-n)
still 5
The dynamic-require
function, like require
, triggers instantion of a
module if it is not already instantiated, so dynamic-require
with #f
as a second argument is useful to just trigger the instantion effects of
a module:
> (module use-n-again racket/base
(require 'number-n)
(printf "also still ~a\n" n))
> (dynamic-require ''use-n-again #f)
also still 5
Instantiation of modules by require
is transitive. That is, if
require
of a module instantiates it, then any module require
d by
that one is also instantiated if it’s not instantiated already
:
> (module number-m racket/base
(provide m)
(define m (random 10))
(printf "picked ~a\n" m))
> (module use-m racket/base
(require 'number-m)
(printf "still ~a\n" m))
> (require 'use-m)
picked 0
still 0
2. Compile-Time Instantiation
In the same way that declaring a module does not by itself instantiate a
module, declaring a module that require
s another module does not by
itself instantiate the require
d module, as illustrated in the
preceding example. However, declaring a module does expand and compile
the module. If a module imports another with (require (for-syntax ....))
, then module that is imported for-syntax
must be instantiated
during expansion:
> (module number-p racket/base
(provide p)
(define p (random 10))
(printf "picked ~a\n" p))
> (module use-p-at-compile-time racket/base
(require (for-syntax racket/base
'number-p))
(define-syntax (pm stx)
#`#,p)
(printf "was ~a at compile time\n" (pm)))
picked 1
Unlike run-time instantiation in a namespace, when a module is used
for-syntax
for another module expansion in the same namespace, the
for-syntax
ed module is instantiated separately for each expansion.
Continuing the previous example, if number-p
is used a second time
for-syntax
, then a second random number is selected for a new p
:
> (module use-p-again-at-compile-time racket/base
(require (for-syntax racket/base
'number-p))
(define-syntax (pm stx)
#`#,p)
(printf "was ~a at second compile time\n" (pm)))
picked 3
Separate compile-time instantiations of number-p
helps prevent
accidental propagation of effects from one module’s compilation to
another module’s compilation. Preventing those effects make compilation
reliably separate and more deterministic.
The expanded forms of use-p-at-compile-time
and
use-p-again-at-compile-time
record the number that was selected each
time, so those two different numbers are printed when the modules are
instantiated:
> (dynamic-require ''use-p-at-compile-time #f)
was 1 at compile time
> (dynamic-require ''use-p-again-at-compile-time #f)
was 3 at second compile time
A namespace’s top level behaves like a separate module, where multiple
interactions in the top level conceptually extend a single expansion of
the module. So, when using (require (for-syntax ....))
twice in the
top level, the second use does not trigger a new compile-time instance:
> (begin (require (for-syntax 'number-p)) 'done)
picked 4
'done
> (begin (require (for-syntax 'number-p)) 'done-again)
'done-again
However, a run-time instance of a module is kept separate from all
compile-time instances, including at the top level, so a
non-for-syntax
use of number-p
will pick another random number:
> (require 'number-p)
picked 5
3. Visiting Modules
When a module provide
s a macro for use by other modules, the other
modules use the macro by directly require
ing the macro provider—i.e.,
without for-syntax
. That’s because the macro is being imported for use
in a run-time position (even though the macro’s implementation lives at
compile time), while for-syntax
would import a binding for use in
compile-time position.
The module implementing a macro, meanwhile, might require
another
module for-syntax
to implement the macro. The for-syntax
module
needs a compile-time instantiation during any module expansion that
might use the macro. That requirement sets up a kind of transitivity
through require
that is similar to instantiation transitivity, but
“off by one” at the point where the for-syntax
shift occurs in the
chain.
Here’s an example to make that scenario concrete:
> (module number-q racket/base
(provide q)
(define q (random 10))
(printf "picked ~a\n" q))
> (module use-q-at-compile-time racket/base
(require (for-syntax racket/base
'number-q))
(provide qm)
(define-syntax (qm stx)
#`#,q)
(printf "was ~a at compile time\n" (qm)))
picked 7
> (module use-qm racket/base
(require 'use-q-at-compile-time)
(printf "was ~a at second compile time\n" (qm)))
picked 4
> (dynamic-require ''use-qm #f)
was 7 at compile time
was 4 at second compile time
In this example, when use-q-at-compile-time
is expanded and compiled,
number-q
is instantiated once. In this case, that instantion is needed
to expand the (qm)
macro, but the module system would proactively
create a compile-time instantiation of number-q
even if the qm
macro
turned out not to be used.
Then, as use-qm
is expanded and compiled, a second compile-time
instantiation of number-q
is created. That compile-time instantion is
needed to expand the (qm)
form within use-qm
.
Instantiating use-qm
correctly reports the number that was picked
during that second module’s compilation. First, though, the require
of
use-q-at-compile-time
in use-qm
triggers a transitive instantiation
of use-q-at-compile-time
, which correctly reports the number that was
picked in its compilation.
Overall, the example illustrates a transitive effect of require
that
we had already seen:
-
When a module is instantiated, the run-time expressions in its body are evaluated.
-
When a module is instantiated, then any module that it
require
swithout `for-syntax`
is also instantiated.
This rule does not explain the compile-time instantiations of
number-q
, however. To explain that, we need a new word, visit, for
the concept that we saw in Compile-Time Instantiation:
-
When a module is visited, the compile-time expressions (such as macro definition) in its body are evaluated.
-
As a module is expanded, it is visited.
-
When a module is visited, then any module that it
require
swithout `for-syntax`
is also visited. -
When a module is visited, then any module that it
require
sfor-syntax
is instantiated at compile time.
Note that when visiting one module causes a compile-time instantion of
another module, the transitiveness of instantiated through regular
require
s can trigger more compile-time instantiations. Instantiation
itself won’t trigger further visits, however, because any instantiated
module has already been expanded and compiled.
The compile-time expressions of a module that are evaluated by visiting
include both the right-hand sides of define-syntax
forms and the body
of begin-for-syntax
forms. That’s why a randomly selected number is
printed immediately in the following example:
> (module compile-time-number racket/base
(require (for-syntax racket/base))
(begin-for-syntax
(printf "picked ~a\n" (random)))
(printf "running\n"))
picked 0.25549265186825576
Instantiating the module evaluates only the run-time expressions, which prints “running” but not a new random number:
> (dynamic-require ''compile-time-number #f)
running
The description of instantiates and visit above is phrased in terms of
normal require
s and for-syntax
require
s, but a more precise
specification is in terms of module phases. For example, if module A
has (require (for-syntax B))
and module B
has (require (for-template C))
, then module C
is instantiated when module A
is
instantiated, because the for-syntax
and for-template
shifts cancel.
We have not yet specified what happens with for-meta 2
for when
for-syntax
es combine; we leave that to the next section, Lazy Visits
via Available Modules.
If you think of the top-level as a kind of module that is continuously
expanded, the above rules imply that require
of another module at the
top level both instantiates and visits the other module (if it is not
already instantiated and visited). That’s roughly true, but the visit
is made lazy in a way that is also explained in the next section, Lazy
Visits via Available Modules.
Meanwhile, dynamic-require
only instantiates a module; it does not
visit the module. That simplification is why some of the preceding
examples use dynamic-require
instead of require
. The extra visits of
a top-level require
would make the earlier examples less clear.
4. Lazy Visits via Available Modules
A top-level require
of a module does not actually visit the module.
Instead, it makes the module available. An available module will be
visited when a future expression needs to be expanded in the same
context. The next expression may or may not involve some imported macro
that needs its compile-time helpers evaluated by visiting, but the
module system proactively visits the module, just in case.
In the following example, a random number is picked as a result of
visiting a module’s own body while that module is being expanded. A
require
of the module instantiates it, printing “running”, and also
makes the module available. Evaluating any other expression implies
expanding the expression, and that expansion triggers a visit of the
available module—which picks another random number:
> (module another-compile-time-number racket/base
(require (for-syntax racket/base))
(begin-for-syntax
(printf "picked ~a\n" (random)))
(printf "running\n"))
picked 0.3634379786893492
> (require 'another-compile-time-number)
running
> 'next
picked 0.5057086679589476
'next
> 'another
'another
Beware that the expander flattens the content of a top-level
begin
into the top level as soon as thebegin
is discovered. So,(begin (require 'another-compile-time-number) 'next)
would still have printed “picked” before “next“.
The final evaluation of 'another
also visits any available modules,
but no modules were made newly available by simply evaluating 'next
.
When a module require
s another module using for-meta n
for some n
greater than 1, the require
d module is made available at phase n
. A
module that is available at phase n
is visited when some expression at
phase n
_-1_ is expanded.
To help illustrate, the following examples use
(variable-reference->module-base-phase (#%variable-reference))
, which
returns a number for the phase at which the enclosing module is
instantiated:
> (module show-phase racket/base
(printf "running at ~a\n"
(variable-reference->module-base-phase (#%variable-reference))))
> (require 'show-phase)
running at 0
> (module use-at-phase-1 racket/base
(require (for-syntax 'show-phase)))
running at 1
> (module unused-at-phase-2 racket/base
(require (for-meta 2 'show-phase)))
For the last module above, show-phase
is made available at phase 2,
but no expressions within the module are ever expanded at phase 1, so
there’s no phase-2 printout. The following module includes a phase-1
expression after the phase-2 require
, so there’s a printout:
> (module use-at-phase-2 racket/base
(require (for-meta 2 'show-phase)
(for-syntax racket/base))
(define-syntax x 'ok))
running at 2
If we require
the module use-at-phase-1
at the top level, then
show-phase
is made available at phase 1. Evaluating another expression
causes use-at-phase-1
to be visited, which in turn instantitates
show-phase
:
> (require 'use-at-phase-1)
> 'next
running at 1
'next
A require
of use-at-phase-2
is similar, except that show-phase
is
made available at phase 2, so it is not instantiated until some
expression is expanded at phase 1:
> (require 'use-at-phase-2)
> 'next
'next
> (require (for-syntax racket/base))
> (begin-for-syntax 'compile-time-next)
running at 2