1.4 API for Making Bytecode
(require compiler/cm) | package: base |
procedure
(make-compilation-manager-load/use-compiled-handler [ delete-zos-when-rkt-file-does-not-exist? #:security-guard security-guard]) → (path? (or/c symbol? false/c) . -> . any) delete-zos-when-rkt-file-does-not-exist? : any/c = #f security-guard : (or/c security-guard? #f) = #f
the file is expected to contain a module (i.e., the second argument to the handler is a symbol);
the value of each of (current-eval), (current-load), and (namespace-module-registry (current-namespace)) is the same as when make-compilation-manager-load/use-compiled-handler was called;
the value of use-compiled-file-paths contains the first path that was present when make-compilation-manager-load/use-compiled-handler was called;
the value of current-load/use-compiled is the result of this procedure; and
one of the following holds:
the source file is newer than the ".zo" file in the first sub-directory listed in use-compiled-file-paths (at the time that make-compilation-manager-load/use-compiled-handler was called), and either no ".dep" file exists or it records a source-file SHA-1 hash that differs from the current version and source-file SHA-1 hash;
no ".dep" file exists next to the ".zo" file;
the version recorded in the ".dep" file does not match the result of (version);
the source hash recorded in the ".dep" file does not match the current source hash;
one of the files listed in the ".dep" file has a ".zo" timestamp newer than the target ".zo" and use-compiled-file-check is set to 'modify-seconds;
the combined hashes of the dependencies recorded in the ".dep" file does not match the combined hash recorded in the ".dep" file.
If SHA-1 hashes override a timestamp-based decision to recompile the file, then the target ".zo" file’s timestamp is updated to the current time, unless the use-compiled-file-check parameter is not set to 'modify-seconds.
After the handler procedure compiles a ".zo" file, it creates a corresponding ".dep" file that lists the current version and the identification of every file that is directly required by the module in the compiled file. Additional dependencies can be installed during compilation via compiler/cm-accomplice. The ".dep" file also records the SHA-1 hash of the module’s source, and it records a combined SHA-1 hash of all of the dependencies that includes their recursive dependencies.
The handler caches timestamps when it checks ".dep" files, and the cache is maintained across calls to the same handler. The cache is not consulted to compare the immediate source file to its ".zo" file, which means that the caching behavior is consistent with the caching of the default module name resolver (see current-module-name-resolver).
If use-compiled-file-paths contains an empty list when make-compilation-manager-load/use-compiled-handler is called, then an exn:fail:contract exception is raised.
If the delete-zos-when-rkt-file-does-not-exist? argument is a true value, then the returned handler will delete ".zo" files when there is no corresponding original source file.
If the security-guard argument is supplied, it is used when creating ".zo" files, ".dep" files, and "compiled/" directories, and when it adjusts the timestamps for existing files. If it is #f, then the security guard in the current-security-guard when the files are created is used (not the security guard at the point make-compilation-manager-load/use-compiled-handler is called).
The continuation of the compilation of a module is marked with a managed-compiled-context-key and the module’s source path.
Do not install the result of
make-compilation-manager-load/use-compiled-handler when the
current namespace contains already-loaded versions of modules that may
need to be recompiled—
The handler logs messages to the topic 'compiler/cm at the level 'info. These messages are instances of a compile-event prefab structure:
(struct compile-event (timestamp path type) #:prefab)
Changed in version 6.1.1.8 of package base: Added identification of the compilation
context via managed-compiled-context-key.
Changed in version 6.6.0.3: added check on a source’s SHA1 hash to complement the
timestamp check, where the latter can be disabled
via use-compile-file-check.
procedure
(managed-compile-zo file [ read-src-syntax #:security-guard security-guard]) → void? file : path-string?
read-src-syntax : (any/c input-port? . -> . syntax?) = read-syntax security-guard : (or/c security-guard? #f) = #f
If file is compiled from source, then read-src-syntax is used in the same way as read-syntax to read the source module. The normal read-syntax is used for any required files, however.
If security-guard is not #f, then the provided security guard is used when creating the "compiled/" directories, ".dep" and ".zo" files, and when it adjusts the timestamps of existing files. If it is #f, then the security guard in the current-security-guard when the files are created is used (not the security guard at the point managed-compile-zo is called).
While compiling file, the error-display-handler parameter is set to (make-compilation-context-error-display-handler (error-display-handler)), so that errors from uncaught exceptions will report the compilation context.
Changed in version 6.1.1.8 of package base: Added error-display-handler configuration.
Added in version 6.1.1.8 of package base.
procedure
(make-compilation-context-error-display-handler orig-handlers)
→ (string? any/c . -> . void?) orig-handlers : (string? any/c . -> . void?)
Added in version 6.1.1.8 of package base.
parameter
(trust-existing-zos trust?) → void? trust? : any/c
procedure
(make-caching-managed-compile-zo [ read-src-syntax #:security-guard security-guard]) → (path-string? . -> . void?)
read-src-syntax : (any/c input-port? . -> . syntax?) = read-syntax security-guard : (or/c security-guard? #f) = #f
parameter
(manager-compile-notify-handler) → (path? . -> . any)
(manager-compile-notify-handler notify) → void? notify : (path? . -> . any)
parameter
(manager-trace-handler) → (string? . -> . any)
(manager-trace-handler notify) → void? notify : (string? . -> . any)
The default value of the parameter logs the argument, along with current-inexact-milliseconds, to a logger named 'compiler/cm at the 'debug level.
parameter
→ (-> path? (or/c (cons/c number? promise?) #f)) (manager-skip-file-handler proc) → void? proc : (-> path? (or/c (cons/c number? promise?) #f))
parameter
→ (or/c #f (-> path? (and/c path? relative-path?))) (current-path->mode path->mode) → void? path->mode : (or/c #f (-> path? (and/c path? relative-path?)))
= #f
Note that this parameter is not used by current-load/use-compiled. So if the parameter causes ".zo" files to be placed in different directories, then the correct ".zo" file must still be communicated via use-compiled-file-paths, and one way to do that is to override current-load/use-compiled to delete ".zo" files that would cause the wrong one to be chosen right before they are loaded.
Added in version 6.4.0.14 of package base.
procedure
(file-stamp-in-paths p paths)
→ (or/c (cons/c number? promise?) #f) p : path? paths : (listof path?)
This function is intended for use with manager-skip-file-handler.
procedure
(get-file-sha1 p) → (or/c string? #f)
p : path?
procedure
(get-compiled-file-sha1 p) → (or/c string? #f)
p : path?
procedure
(with-compile-output p proc) → any
p : path-string? proc : ([port input-port?] [tmp-path path?] . -> . any)
parameter
→
(or/c #f (->i ([command (or/c 'lock 'unlock)] [file bytes?]) [res (command) (if (eq? command 'lock) boolean? void?)])) (parallel-lock-client proc) → void?
proc :
(or/c #f (->i ([command (or/c 'lock 'unlock)] [file bytes?]) [res (command) (if (eq? command 'lock) boolean? void?)]))
When proc is #f (the default), no checking for parallel compilation is done (and thus multiple threads or places running compilations via make-compilation-manager-load/use-compiled-handler will potentially corrupt each other’s ".zo" files).
When proc is a function, its first argument is a command, indicating if it wants to lock or unlock the path specified in the second argument.
When the proc 'lock command returns #t, the current builder has obtained the lock for zo-path. Once compilation of zo-path is complete, the builder process must release the lock by calling proc 'unlock with the exact same zo-path.
When the proc 'lock command returns #f, another parallel builder obtained the lock first and has already compiled the zo. The parallel builder should continue without compiling zo-path. (In this case, make-compilation-manager-load/use-compiled-handler’s result will not call proc with 'unlock.)
> (let* ([lc (parallel-lock-client)] [zo-name #"collects/racket/compiled/draw_rkt.zo"] [locked? (and lc (lc 'lock zo-name))] [ok-to-compile? (or (not lc) locked?)]) (dynamic-wind (lambda () (void)) (lambda () (when ok-to-compile? (printf "Do compile here ...\n"))) (lambda () (when locked? (lc 'unlock zo-name))))) Do compile here ...
procedure
(compile-lock->parallel-lock-client pc [ cust]) → (-> (or/c 'lock 'unlock) bytes? boolean?) pc : place-channel? cust : (or/c #f custodian?) = #f
This communication protocol implementation is not kill safe. To make it kill safe, it needs a sufficiently powerful custodian, i.e., one that is not subject to termination (unless all of the participants in the compilation are also terminated). It uses this custodian to create a thread that monitors the threads that are doing the compilation. If one of them is terminated, the presence of the custodian lets another one continue. (The custodian is also used to create a thread that manages a thread safe table.)
procedure
(make-compile-lock) → place-channel?
procedure
(install-module-hashes! bstr [start end]) → void?
bstr : bytes? start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bstr)
Added in version 6.3 of package base.