yield in Eventspaces

Yields control to event dispatching. See Eventspaces for details.

A handler procedure invoked by the system during a call to yield can itself call yield, creating an additional level of nested (but single-threaded) event handling.

See also sleep/yield .

• (yield) -> boolean

  Dispatches an unspecified number of events, but only if the current thread is the current eventspace's handler thread (otherwise, there is no effect). The result is #t if any events may have been handled, #f otherwise.

  
  

• (yield v) -> value
     v : 'wait or waitable

  If v is 'wait, and yield is called in the handler thread of an eventspace, it starts processing events in that eventspace until

  • no top-level windows in the eventspace are visible;

  • no timers in the eventspace are running;

  • no callbacks are queued in the eventspace; and

  • no menu-bar% has been created for the eventspace with 'root (i.e., creating a 'root menu bar prevents an eventspace from ever unblocking).

  When called in a non-handler thread, returns immediately. In either case, the result is #t.

  Evaluating (yield 'wait) is thus similar to (yield (current-eventspace)), except that it is sensitive to whether the current thread is a handler thread, instead of the value of the current-eventspace parameter.

  If v is a waitable, yield blocks on v in the same way as MzScheme's object-wait-multiple, section 7.6 in PLT MzScheme: Language Manual, except that it may poll or wait on the waitable multiple times. If the current thread is the current eventspace's handler thread, events are dispatched until a v wait succeeds on an event boundary. For other threads, calling yield with a waitable is equivalent to calling object-wait-multiple with #f as the timeout. In either case, the result is the same that of object-wait-multiple; however, if a wrapper procedure is associated with v (via make-wrapped-waitable), it is not called in tail position with respect to the yield.

  Always use (yield v) instead of a busy-wait loop.