eval-in-listener-thread

Arguments: form &key wait (listener :selected) funcall trap-errors

Evaluates an arbitrary lisp form in either an IDE listener thread or the IDE GUI thread. Optionally waits for the evaluation to complete, returning the result of the evaluation. This function may be useful when customizing the IDE if it is necessary to evaluate a form in a thread other than what the IDE would use by default.

The IDE creates its tool windows in the IDE GUI thread, and runs the code for those windows in that thread. On the other hand, user code that is evaluated in an IDE Listener or with the Tools | Graph Subclasses and Tools | Incremental Evaluation command is run in an IDE Listener thread. This multi-threaded design allows IDE tool windows to respond while an evaluation of user code is still busy. In certain cases, this may result in code being run in an inappropriate thread. For example, if you define a global keyboard accelerator (see add-global-keyboard-accelerator) and use it in an IDE tool window, then its code will run in the IDE GUI thread that created that window. If that code should instead run in an IDE Listener thread in order to run in the same environment as other user code, then this can be achieved by calling eval-in-listener-thread in the global keyboard accelerator code.

form is the Lisp form to be evaluated. Note that because this argument is evaluated by the reader (as are all arguments to functions), the value of form should evaluate to the Lisp form to be evaluated. This is done in the examples below by quoting the desired form.

If wait is true, then eval-in-listener-thread does not return until the specified thread has finished the evaluation, at which time eval-in-listener-thread returns the values that were returned by calling eval on form.

If wait is nil (the default), then eval-in-listener-thread returns immediately after posting a notification to the specified thread, and the returned value is undefined. An exception is that if the specified listener indicates the current thread, then eval is called on form directly, and so eval-in-listener-thread does not return until the evaluation is done even if wait is nil.

listener indicates the thread in which the evaluation will be done. It must be either :selected (the default), :initial, or :gui. :selected means to evaluate the form in the thread of the IDE listener pane that is currently selected in the Debug Window. This is the same thread in which forms that are typed into the Debug Window are evaluated, and the thread in which IDE commands such as "Tools | Incremental Eval" and "File | Load" evaluate user code. :initial means to evaluate the form in the thread of the "Listener 1" listener, which is always present in the IDE (it cannot be closed except by exiting the IDE). :gui means to evaluate the form in the "IDE GUI" thread, which is not a listener thread at all but rather a special IDE thread that handles mouse and keyboard events in IDE windows. It is probably not usually appropriate for user code to be evaluated in the IDE GUI thread, except for IDE customizations that manipulate IDE windows (which are created in the IDE GUI thread).

If funcall is true, form is passed to funcall rather than to eval. form must then be a suitable argument to funcall and will be passed with no arguments.

If trap-errors is true, then any errors that are signaled are ignored. If wait is also true and an error is signaled, then eval-in-listener-thread will return two values: (1) the keyword symbol :eval-in-listener-thread-error and (2) the error condition.

Note that this function is useful only in the IDE, rather than in standalone CG applications. The IDE creates a particular set of threads and has conventions for which thread to use for particular tasks. These conventions may not be suitable for some IDE customizations, and so this function is provided to avoid any such problems. A standalone CG app that uses multiple threads, on the other hand, must handle its own thread management.

Examples:

(ide:eval-in-listener-thread
  '(mp:process-name sys:*current-process*)
  :wait t :listener :initial)
==> "Listener 1"

(ide:eval-in-listener-thread
  '(mp:process-name sys:*current-process*)
  :wait t :listener :gui)
==> "IDE GUI"

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.