Tcl_DoWhenIdle, Tcl_CancelIdleCall - invoke a procedure
when there are no pending events
Tcl_IdleProc *proc (in) Procedure to invoke.
ClientData clientData (in) Arbitrary one-word
value to pass to
Tcl_DoWhenIdle arranges for proc to be invoked when the
application becomes idle. The application is considered
to be idle when Tcl_DoOneEvent has been called, couldn't
find any events to handle, and is about to go to sleep
waiting for an event to occur. At this point all pending
Tcl_DoWhenIdle handlers are invoked. For each call to
Tcl_DoWhenIdle there will be a single call to proc; after
proc is invoked the handler is automatically removed.
Tcl_DoWhenIdle is only usable in programs that use
Tcl_DoOneEvent to dispatch events.
Proc should have arguments and result that match the type
typedef void Tcl_IdleProc(ClientData clientData);
The clientData parameter to proc is a copy of the client
Data argument given to Tcl_DoWhenIdle. Typically, client
Data points to a data structure containing application-
specific information about what proc should do.
Tcl_CancelIdleCall may be used to cancel one or more pre
vious calls to Tcl_DoWhenIdle: if there is a
Tcl_DoWhenIdle handler registered for proc and clientData,
then it is removed without invoking it. If there is more
than one handler on the idle list that refers to proc and
clientData, all of the handlers are removed. If no exist
ing handlers match proc and clientData then nothing hap
Tcl_DoWhenIdle is most useful in situations where (a) a
piece of work will have to be done but (b) it's possible
to be done. Tcl_DoWhenIdle allows the actual work to be
deferred until all pending events have been processed. At
this point the exact work to be done will presumably be
known and it can be done exactly once.
For example, Tcl_DoWhenIdle might be used by an editor to
defer display updates until all pending commands have been
processed. Without this feature, redundant redisplays
might occur in some situations, such as the processing of
a command file.
At present it is not safe for an idle callback to resched
ule itself continuously. This will interact badly with
certain features of Tk that attempt to wait for all idle
callbacks to complete. If you would like for an idle
callback to reschedule itself continuously, it is better
to use a timer handler with a zero timeout period.
callback, defer, idle callback