eval-in-listener-thread

Function

Package: common-graphics

Arguments: form &key wait (listener :selected)

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. (One example is when a global keyboard accelerator is added by add-global-keyboard-accelerator wants to do evaluation in the Debug Window.)

form is the lisp form to be evaluated.

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).

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:

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

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

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.