14.2 Evaluation and Compilation (original) (raw)

14.2 Evaluation and Compilation🔗ℹ

+Reflection and Dynamic Evaluation in The Racket Guide introduces dynamic evaluation.

Racket provides programmatic control over evaluation througheval and related functions. See Controlling and Inspecting Compilation for information about extra-linguistic facilities related to the Racket compiler.

A parameter that determines the current evaluation handler. The evaluation handler is a procedure that takes a top-level form and evaluates it, returning the resulting values. The evaluation handler is called by eval, eval-syntax, the defaultload handler, and read-eval-print-loop to evaluate a top-level form. The handler should evaluate its argument in tail position.

The top-level-form provided to the handler can be asyntax object, a compiled form, a compiled form wrapped as a syntax object, or an arbitrary datum.

The default handler converts an arbitrary datum to a syntax object using datum->syntax, and then enriches its lexical information in the same way as eval. (Iftop-level-form is a syntax object, then its lexical information is not enriched.) The default evaluation handler partially expands the form to splice the body of top-levelbegin forms into the top level (seeexpand-to-top-form), and then individually compiles and evaluates each spliced form before continuing to expand, compile, and evaluate later forms.

Calls the current evaluation handler to evaluatetop-level-form. The evaluation handler is called in tail position with respect to the eval call. An evaluation handler uses the current namespace; in the two-argument case ofeval, the call to the evaluation handler isparameterized to set current-namespace tonamespace.

If top-level-form is a syntax object whose datum is not a compiled form, then its lexical information is enriched before it is sent to the evaluation handler:

For interactive evaluation in the style ofread-eval-print-loop and load, wrap each expression with #%top-interaction, which is normally bound to#%top-interaction, before passing it to eval.

Like eval, except that stx must be a syntax object, and its lexical context is not enriched before it is passed to theevaluation handler.

A parameter that determines the current load handler to load top-level forms from a file. The load handler is called byload, load-relative, load/cd, and the default compiled-load handler.

A load handler takes two arguments: a path (see Paths) and an expected module name. The expected module name is a symbol or a list when the call is to load a module declaration in response to arequire (in which case the file should contain a module declaration), or #f for any other load.

When loading a module from a stream that starts with a compiled module that contains submodules, the load handler should load only the requested module, where a symbol as the load handler’s indicates the root module and a list indicates a submodule whose path relative to the root module is given by the cdr of the list. The list starts with #f when a submodule should be loaded onlyif it can be loaded independently (i.e., from compiled form—never from source); if the submodule cannot be loaded independently, the load handler should return without loading from a file. When the expected module name is a list that starts with a symbol, the root module and any other submodules can be loaded from the given file, which might be from source, and the load handler still should not complain if the expected submodule is not found. When loading modules from a nonexistent source file, the load handler may raise an exception regardless of whether submodules are requested or not.

The default load handler reads forms from the file inread-syntax mode with line-counting enabled for the file port, unless the path has a ".zo" suffix. It alsoparameterizes each read to set read-accept-compiled,read-accept-reader, and read-accept-lang to#t. In addition, if load-on-demand-enabled is#t, then read-on-demand-source is set to the cleansed, absolute form of path during theread-syntax call. After reading a single form, the form is passed to the current evaluation handler, wrapping the evaluation in a continuation prompt (seecall-with-continuation-prompt) for the default continuation prompt tag with handler that propagates the abort to the continuation of the load call.

If the second argument to the load handler is a symbol, then:

If the second argument to the load handler is #f, then each expression read from the file is wrapped with#%top-interaction, which is normally bound to#%top-interaction, before passing it to the evaluation handler.

The return value from the default load handler is the value of the last form from the loaded file, or # if the file contains no forms. If the given path is a relative path, then it is resolved using the value of current-directory.

Calls the current load handler in tail position. The call isparameterized to set current-load-relative-directoryto the directory of file, which is resolved relative to the value of current-directory.

Like load/use-compiled, but when file is a relative path, it is resolved using the value ofcurrent-load-relative-directory instead of the value ofcurrent-directory if the former is not #f, otherwisecurrent-directory is used.

A parameter that determines a extension-load handler, which is called by load-extension and the default compiled-load handler.

An extension-load handler takes the same arguments as aload handler, but the file should be a platform-specificdynamic extension, typically with the file suffix".so" (Unix), ".dll" (Windows), or ".dylib"(Mac OS). The file is loaded using internal, OS-specific primitives. See Inside: Racket C API for more information ondynamic extensions.

Extensions are supported only when (system-type 'vm) returns'racket.

Sets current-load-relative-directory like load, and calls the extension-load handler in tail position.

Extensions are supported only when (system-type 'vm) returns'racket.

Like load-extension, but resolves file usingcurrent-load-relative-directory like load-relative.

Extensions are supported only when (system-type 'vm) returns'racket.

A parameter that determines the current compiled-load handler to load from a file that may have a compiled form. Thecompiled-load handler is called by load/use-compiled.

The protocol for a compiled-load handler is the same as for theload handler (see current-load), except that acompiled-load handler is expected to setcurrent-load-relative-directory itself. Additionally, the defaultcompiled-load handler does the following:

The check for a compiled file occurs whenever the given pathfile ends with any extension (e.g., ".rkt" or".scrbl"), and the check consults the subdirectories indicated by the current-compiled-file-roots anduse-compiled-file-paths parameters relative tofile, where the former supplies “roots” for compiled files and the latter provides subdirectories.See also compiler/compilation-path.A “root” can be an absolute path, in which case file’s directory is combined withreroot-path and the root as the second argument; if the “root” is a relative path, then the relative path is instead suffixed onto the directory of file. The roots are tried in order, and the subdirectories are checked in order within each root. A".zo" version of the file (whose name is formed by passingfile and #".zo" to path-add-extension) is loaded if it exists directly in one of the indicated subdirectories, or when (system-type 'vm) returns'racket, then a ".so"/".dll"/".dylib" version of the file is loaded if it exists within a "native" subdirectory of a use-compiled-file-paths directory, in an even deeper subdirectory as named by system-library-subpath. A compiled file is loaded only if it checks out according to(use-compiled-file-check); with the default parameter value of 'modify-seconds, a compiled file is used only if its modification date is not older than the date for file. If both ".zo" and".so"/".dll"/".dylib" files are available when (system-type 'vm) returns 'racket, the ".so"/".dll"/".dylib" file is used. Iffile ends with ".rkt", no such file exists, the handler’s second argument is a symbol, and a ".ss" file exists, then ".zo" and".so"/".dll"/".dylib" files are used only with names based on file with its suffixed replaced by".ss".

While a ".zo", ".so", ".dll", or".dylib" file is loaded, the current load-relativedirectory is set to the directory of the original file. If the file to be loaded has the suffix ".ss" while the requested file has the suffix ".rkt", then thecurrent-module-declare-source parameter is set to the full path of the loaded file, otherwise thecurrent-module-declare-source parameter is set to#f.

If the original file is loaded or a ".zo" variant is loaded, the load handler is called to load the file. If any other kind of file is loaded, the extension-load handler is called.

When the default compiled-load handler loads a module from a bytecode (i.e., ".zo") file, the handler records the bytecode file path in the current namespace’s module registry. More specifically, the handler records the path for the top-level module of the loaded module, which is an enclosing module if the loaded module is a submodule. Thereafter, loads via the default compiled-load handler for modules within the same top-level module use the recorded file, independent of the file that otherwise would be selected by thecompiled-load handler (e.g., even if theuse-compiled-file-paths parameter value changes). The defaultmodule name resolver transfers bytecode-file information when a module declaration is attached to a new namespace. This protocol supports independent but consistent loading of submodules from bytecode files.

Calls the current compiled-load handler in tail position.

A parameter that is set by load, load-relative,load-extension, load-relative-extension, and the default compiled-load handler, and used byload-relative, load-relative-extension, and the default compiled-load handler.

When a new path or string is provided as the parameter’s value, it is immediately expanded (see Paths) and converted to a path. (The directory need not exist.)

A list of relative paths, which defaults to (list (string->path "compiled")). It is used by the compiled-load handler (see current-load/use-compiled).

If the PLT_ZO_PATH environment variable is set on startup, it supplies a path instead of "compiled" to use for the initial parameter value.

Changed in version 7.7.0.9 of package base: Added PLT_ZO_PATH.

A list of paths and 'sames that is used by the defaultcompiled-load handler (see current-load/use-compiled).

The parameter is normally initialized to (list 'same), but the parameter’s initial value can be adjusted by the installation configuration as reported by (find-compiled-file-roots), and it can be further adjusted by thePLTCOMPILEDROOTS environment variable or the--compiled or -R command-line flag for racket. If the environment variable is defined and not overridden by a command-line flag, it is parsed by first replacing any@(version) with the result of (version), then usingpath-list-string->path-list with a path list produced by(find-compiled-file-roots) to arrive at the parameter’s initial value.

Produces a list of paths and 'same, which is normally used to initialize current-compiled-file-roots. The list is determined by consulting the "config.rtkd" file in the directory reported by (find-config-dir), and it defaults to(list 'same) if not configured there.

See also 'compiled-file-roots in Installation Configuration and Search Paths.

Added in version 8.0.0.9 of package base.

(use-compiled-file-check) → (or/c 'modify-seconds 'exists)
(use-compiled-file-check check) → void?
check : (or/c 'modify-seconds 'exists)

A parameter that determines how a compiled file is checked against its source to enable use of the compiled file. By default, the file-check mode is 'modify-seconds, which uses a compiled file when its filesystem modification date is at least as new as the source file’s. The 'exists mode causes a compiled file to be used in place of its source as long as the compiled file exists.

If the PLT_COMPILED_FILE_CHECK environment variable is set to modify-seconds or exists, then the environment variable’s value configures the parameter when Racket starts.

Added in version 6.6.0.3 of package base.

Starts a new REPL using the current input, output, and error ports. The REPL wraps each expression to evaluate with#%top-interaction, which is normally bound to#%top-interaction, and it wraps each evaluation with a continuation prompt using the default continuation prompt tag and prompt handler (see call-with-continuation-prompt). The REPL also wraps the read and print operations with a prompt for the default tag whose handler ignores abort arguments and continues the loop. Theread-eval-print-loop procedure does not return untileof is read, at which point it returns #.

The read-eval-print-loop procedure can be configured through the current-prompt-read, current-eval, andcurrent-print parameters.

A parameter that determines a prompt read handler, which is a procedure that takes no arguments, displays a prompt string, and returns a top-level form to evaluate. The prompt read handler is called by read-eval-print-loop, and after printing a prompt, the handler typically should call the read interaction handler(as determined by the current-read-interaction parameter) with the port produced by the interaction port handler(as determined by the current-get-interaction-input-port parameter).

The default prompt read handler prints > and returns the result of

If the input and output ports are both terminals (in the sense ofterminal-port?) and if the output port appears to be counting lines (because port-next-location returns a non-#fline and column), then the output port’s line is incremented and its column is reset to 0 via set-port-next-location!before returning the read result.

A parameter that determines the interaction port handler, which returns a port to use for read-eval-print-loop inputs.

The default interaction port handler returns the current input port. In addition, if that port is the initial current input port, the initial current output and error ports are flushed.

The racket/gui/base library adjusts this parameter’s value by extending the current value. The extension wraps the result port so that GUI events can be handled when reading from the port blocks.

A parameter that determines the interaction event handler, which returns an synchronizable event that should be used in combination with blocking that is similar toread-eval-print-loop waiting for input—but where an input port is not read directly, socurrent-get-interaction-input-port does not apply.

When the interaction event handler returns an event that becomes ready, and when the event’s ready value is a procedure, then the procedure is meant to be called with zero arguments blocking resumes. The default interaction event handler returns never-evt.

The racket/gui/base library adjusts this parameter’s value by extending the current value. The extension combines the current value’s result with choice-evt and an event that becomes ready when a GUI event is available, and the event’s value is a procedure that yields to one or more available GUI events.

Added in version 8.3.0.3 of package base.

A parameter that determines the current read interaction handler, which is procedure that takes an arbitrary value and an input port and returns an expression read from the input port.

The default read interaction handler accepts src andin and returns

A parameter that determines the print handler that is called by read-eval-print-loop to print the result of an evaluation (and the result is ignored).

The default print handler prints the value to the current output port (as determined by thecurrent-output-port parameter) and then outputs a newline, except that it prints nothing when the value is #.

A parameter that determines the current compilation handler. The compilation handler is a procedure that takes a top-level form and returns a compiled form; see Compilation for more information on compilation.

The compilation handler is called by compile, and indirectly by the default evaluation handler and the defaultload handler.

The handler’s second argument is #t if the compiled form will be used only for immediate evaluation, or #f if the compiled form may be saved for later use; the default compilation handler is optimized for the special case of immediate evaluation.

When a compiled form is written to an output port, the written form starts with #~. See Printing Compiled Code for more information.

For internal testing purposes, when thePLT_VALIDATE_COMPILE environment variable is set, the default compilation handler runs a bytecode validator immediately on its own compilation results (instead of relying only on validation when compiled bytecode is loaded).

The current-compile binding is provided as protectedin the sense of protect-out.

Changed in version 8.2.0.4 of package base: Changed binding to protected.

(compile top-level-form) → compiled-expression?
top-level-form : any/c

Like eval, but calls the current compilation handler in tail position with top-level-form.

Like eval-syntax, but calls the current compilation handler in tail position with stx.

Recompiles ce. If ce was compiled as machine-independent and current-compile-target-machine is not set to #f, then recompiling effectively converts to the current machine format. Otherwise, recompiling effectively re-runs optimization passes to produce an equivalent compiled form with potentially different performance characteristics.

Added in version 6.3 of package base.

Returns a compiled expression like ce, but augments or replaces cross-compilation information in ce with information from other-ce. The intent is that ce andother-ce have been compiled with different values forcurrent-compile-target-machine, and ce will be used to run a module on the compiling machine, while information fromother-ce is needed for cross-compiling imports of the module.

Added in version 8.12.0.3 of package base.

Returns #t if v is a compiled form, #fotherwise.

A parameter that determines how a module declaration is compiled.

When constants are enforced, and when the macro-expanded body of a module contains no set! assignment to a particular variable defined within the module, then the variable is marked as constant when the definition is evaluated. Afterward, the variable’s value cannot be assigned or undefined through module->namespace, and it cannot be defined by redeclaring the module.

Enforcing constants allows the compiler to inline some variable values, and it allows the native-code just-in-time compiler to generate code that skips certain run-time checks.

A parameter that determines how a set! expression is compiled when it mutates a global variable. If the value of this parameter is a true value, set! expressions for global variables are compiled so that the global variable is set even if it was not previously defined. Otherwise, set! expressions for global variables are compiled to raise theexn:fail:contract:variable exception if the global variable is not defined at the time the set! is performed. Note that this parameter is used when an expression is compiled, not when it is evaluated.

A parameter that determines whether compilation should avoid function-call inlining and other optimizations that may cause information to be lost from stack traces (as reported bycontinuation-mark-set->context). The default is #f, which allows such optimizations.

A parameter that determines the platform and/or virtual machine target for a newly compiled expression.

If the target is #f, the the compiled expression writes in a machine-independent format (usually in ".zo" files). Machine-independent compiled code works for any platform and any Racket virtual machine. When the machine-independent compiled expression is read back in, it is subject to further compilation for the current platform and virtual machine, which can be considerably slower than reading a format that is fully compiled for a platform and virtual machine.

The default is something other than #f, unless machine-independent mode is enabled through the-M/--compile-any command-line flag to stand-alone Racket (or GRacket) or through the PLT_COMPILE_ANYenvironment variable (set to any value).

Added in version 7.1.0.6 of package base.

Reports whether sym is a supported compilation target for the currently running Racket.

When (system-type 'vm) reports 'racket, then the only target symbol is 'racket. When (system-type 'vm) reports 'chez-scheme, then a symbol corresponding to the current platform is a target, and other targets may also be supported. The 'target-machine mode of system-typereports the running Racket’s native target machine.

Added in version 7.1.0.6 of package base.

Determines the realm that is assigned to modules and procedures when they are compiled.

Added in version 8.4.0.2 of package base.

A parameter that determines whether the native-code just-in-time compiler (JIT) is enabled for code (compiled or not) that is passed to the default evaluation handler. A true parameter value is effective only on platforms for which the JIT is supported and for Racket virtual machines that rely on a JIT.

The default is #t, unless the JIT is not supported by the current platform but is supported on the same virtual machine for other platforms, unless it is disabled through the-j/--no-jit command-line flag to stand-alone Racket (or GRacket), and unless it is disabled through thePLTNOMZJIT environment variable (set to any value).

A parameter that determines whether the default load handlersets read-on-demand-source. See current-load for more information. The default is #t, unless it is disabled through the -d/--no-delay command-line flag.