On this page:
drracket:  module-language-tools:  add-opt-out-toolbar-button
drracket:  module-language-tools:  add-opt-in-toolbar-button
drracket:  module-language-tools:  add-online-expansion-handler
drracket:  module-language-tools:  add-online-expansion-monitor
drracket:  module-language-tools:  start?
drracket:  module-language-tools:  register-online-expansion-pref
drracket:  module-language-tools:  done?
drracket:  module-language-tools:  done

23 drracket:module-language-tools

procedure

(drracket:module-language-tools:add-opt-out-toolbar-button 
  make-button 
  id 
  [#:number number]) 
  void?
  make-button : 
(-> (is-a?/c top-level-window<%>)
    (is-a?/c area-container<%>)
    (is-a?/c switchable-button%))
  id : symbol?
  number : (or/c real? #f) = #f
Call this function to add another button to DrRacket’s toolbar. When buttons are added this way, DrRacket monitors the #lang line at the top of the file; when it changes DrRacket queries the language to see if this button should be included. These buttons are “opt out”, meaning that if the language doesn’t explicitly ask to not have this button (or all such buttons), the button will appear. See drracket:opt-out-toolbar-buttons for more information.

The number argument is the same as the number argument to register-toolbar-button.

procedure

(drracket:module-language-tools:add-opt-in-toolbar-button 
  make-button 
  id 
  [#:number number]) 
  void?
  make-button : 
(-> (is-a?/c top-level-window<%>)
    (is-a?/c area-container<%>)
    (is-a?/c switchable-button%))
  id : symbol?
  number : (or/c real? #f) = #f
Like drracket:module-language-tools:add-opt-out-toolbar-button, but for buttons that should not be enabled by default, but instead explicitly opted in by languages via drracket:opt-in-toolbar-buttons.

Added in version 1.6 of package drracket.

procedure

(drracket:module-language-tools:add-online-expansion-handler 
  mod-path 
  id 
  local-handler) 
  void?
  mod-path : path-string?
  id : symbol?
  local-handler : 
(-> (is-a?/c drracket:unit:definitions-text<%>)
    any/c
    any)
Registers a pair of procedures with DrRacket’s online expansion machinery. (See also drracket:module-language-tools:add-online-expansion-monitor.)

The procedure id from mod-path is loaded by dynamic-require into a specially designed separate place. When DrRacket detects that the editor has been modified, it sends the contents of the editor over to that separate place, expands the program there, and then supplies the fully expanded object to that first procedure. (The procedure is called in the same context as the expansion process.)

If the expansion raises an exception, then that exception is supplied as the first argument instead of the syntax object. If a non-exn? is raised, or if the expansion process is terminated (e.g. via custodian-shutdown-all called during expansion), then the expansion monitor is not notified.

The contract for that procedure is
There are three other arguments:
  • The path? argument is the path that was the current-directory when the code was expanded. This directory should be used as the current-directory when resolving module paths obtained from the syntax object.

  • The third argument is the source object used in the syntax objects that come from the definitions window in DrRacket. It may be a path (if the file was saved), but it also might not be. Use equal? to compare it with the syntax-source field of syntax objects to determine if they come from the definitions window.

  • Note that the thread that calls this procedure may be killed at any time: DrRacket may kill it when the user types in the buffer (in order to start a new expansion), but bizarro code may also create a separate thread during expansion that lurks around and then mutates arbitrary things.

    Some code, however, should be longer running, surviving such custodian shutdowns. To support this, the procedure called in the separate place is supplied with a more powerful custodian that is not shut down.

The result of the procedure is expected to be something that can be sent across a place-channel, which is then sent back to the original place where DrRacket itself is running and passed to the local-handler argument. At this point, the only code running is trusted code (DrRacket itself and other tools), but any long running computations may freeze DrRacket’s GUI, since this procedure is invoked on DrRacket’s eventspace’s handler thread.

procedure

(drracket:module-language-tools:add-online-expansion-monitor 
  mod-path 
  id 
  local-handler) 
  void?
  mod-path : path-string?
  id : symbol?
  local-handler : 
(-> (is-a?/c drracket:unit:definitions-text<%>)
    (or/c drracket:module-language-tools:start?
          any/c)
    any)
Registers a pair of procedures with DrRacket’s online expansion machinery.

Like drracket:module-language-tools:add-online-expansion-handler, the first two arguments specify a procedure that is called in the separate place designated for expansion.

The procedure is called before expansion starts and once it returns, expansion begins. The procedure should match this contract:
(-> (-> any/c void?)
    path? any/c custodian?
    any)
The first argument is a function that transmits its argument back to the DrRacket place, send it to the local-handler argument. The other three arguments are the same as the corresponding procedure used by drracket:module-language-tools:add-online-expansion-handler.

The expectation is that this procedure creates a thread and monitors the expansion process, sending back information to the main place while expansion is progressing.

The local-handler procedure is called each time the (-> any/c void?) procedure (described just above) is called. It is also called each time an expansion starts; it receives a value that returns #t from drracket:module-language-tools:start? in that case.

To help with debugging, DrRacket logs progress and recovers from some errors that happen when running the handler procedures. To monitor its progress, monitor the 'debug level of the logger with the topic 'drracket-background-compilation.

procedure

(drracket:module-language-tools:start? val)  boolean?

  val : any/c
Returns #t if this is a special (unique) value, used as discussed in drracket:module-language-tools:add-online-expansion-monitor. Returns #f otherwise.
Registers func so that it is called while building the preferences panel. The function is passed a panel that contains other configuration controls for online expansion.

procedure

(drracket:module-language-tools:done? val)  boolean?

  val : any/c
Returns #t for drracket:module-language-tools:done and #f otherwise.
Used to inform a monitor-based handler that the online expansion has finished.