Tcl_DoWhenIdle, Tcl_CancelIdleCall - invoke a procedure when there are no
pending events
#include <tcl.h>
Tcl_DoWhenIdle(proc, clientData)
Tcl_CancelIdleCall(proc, clientData)
- Tcl_IdleProc *proc (in)
- Procedure to invoke.
- ClientData clientData (in)
- Arbitrary one-word value to pass to proc.
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, could not 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
Tcl_IdleProc:
typedef void Tcl_IdleProc(
ClientData clientData);
The
clientData parameter to
proc is a copy of the
clientData argument given to
Tcl_DoWhenIdle. Typically,
clientData points to a data structure containing application-specific
information about what
proc should do.
Tcl_CancelIdleCall may be used to cancel one or more previous 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 existing
handlers match
proc and
clientData then nothing happens.
Tcl_DoWhenIdle is most useful in situations where (a) a piece of work
will have to be done but (b) it is possible that something will happen in the
near future that will change what has to be done or require something
different 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 reschedule 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.
after(3tcl),
Tcl_CreateFileHandler(3tcl),
Tcl_CreateTimerHandler(3tcl)
callback, defer, idle callback