diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:51:12 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2017-09-22 18:51:12 (GMT) |
commit | 3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7 (patch) | |
tree | 69afbb41089c8358615879f7cd3c4cf7997f4c7e /tcl8.6/doc/Notifier.3 | |
parent | a0e17db23c0fd7c771c0afce8cce350c98f90b02 (diff) | |
download | blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.zip blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.tar.gz blt-3fa8e6dc88e8041b6cb88d1b1e9c05676d3346b7.tar.bz2 |
update to tcl/tk 8.6.7
Diffstat (limited to 'tcl8.6/doc/Notifier.3')
-rw-r--r-- | tcl8.6/doc/Notifier.3 | 635 |
1 files changed, 0 insertions, 635 deletions
diff --git a/tcl8.6/doc/Notifier.3 b/tcl8.6/doc/Notifier.3 deleted file mode 100644 index 16f9f8d..0000000 --- a/tcl8.6/doc/Notifier.3 +++ /dev/null @@ -1,635 +0,0 @@ -'\" -'\" Copyright (c) 1998-1999 Scriptics Corporation -'\" Copyright (c) 1995-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Notifier 3 8.1 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier \- the event queue and notifier interfaces -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -void -\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR) -.sp -void -\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR) -.sp -void -\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR) -.sp -void -\fBTcl_QueueEvent\fR(\fIevPtr, position\fR) -.sp -void -\fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR) -.sp -void -\fBTcl_ThreadAlert\fR(\fIthreadId\fR) -.sp -Tcl_ThreadId -\fBTcl_GetCurrentThread\fR() -.sp -void -\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) -.sp -ClientData -\fBTcl_InitNotifier\fR() -.sp -void -\fBTcl_FinalizeNotifier\fR(\fIclientData\fR) -.sp -int -\fBTcl_WaitForEvent\fR(\fItimePtr\fR) -.sp -void -\fBTcl_AlertNotifier\fR(\fIclientData\fR) -.sp -void -\fBTcl_SetTimer\fR(\fItimePtr\fR) -.sp -int -\fBTcl_ServiceAll\fR() -.sp -int -\fBTcl_ServiceEvent\fR(\fIflags\fR) -.sp -int -\fBTcl_GetServiceMode\fR() -.sp -int -\fBTcl_SetServiceMode\fR(\fImode\fR) -.sp -void -\fBTcl_ServiceModeHook\fR(\fImode\fR) -.sp -void -\fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR) -.SH ARGUMENTS -.AS Tcl_EventDeleteProc *notifierProcPtr -.AP Tcl_EventSetupProc *setupProc in -Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR. -.AP Tcl_EventCheckProc *checkProc in -Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for -events. Checks to see if any events have occurred and, if so, -queues them. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or -\fIdeleteProc\fR. -.AP "const Tcl_Time" *timePtr in -Indicates the maximum amount of time to wait for an event. This -is specified as an interval (how long to wait), not an absolute -time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR -is NULL, it means there is no maximum wait time: wait forever if -necessary. -.AP Tcl_Event *evPtr in -An event to add to the event queue. The storage for the event must -have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR. -.AP Tcl_QueuePosition position in -Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR, -\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR. -.AP Tcl_ThreadId threadId in -A unique identifier for a thread. -.AP Tcl_EventDeleteProc *deleteProc in -Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR. -.AP int flags in -What types of events to service. These flags are the same as those -passed to \fBTcl_DoOneEvent\fR. -.AP int mode in -Indicates whether events should be serviced by \fBTcl_ServiceAll\fR. -Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR. -.AP Tcl_NotifierProcs* notifierProcPtr in -Structure of function pointers describing notifier procedures that are -to replace the ones installed in the executable. See -\fBREPLACING THE NOTIFIER\fR for details. -.BE -.SH INTRODUCTION -.PP -The interfaces described here are used to customize the Tcl event -loop. The two most common customizations are to add new sources of -events and to merge Tcl's event loop with some other event loop, such -as one provided by an application in which Tcl is embedded. Each of -these tasks is described in a separate section below. -.PP -The procedures in this manual entry are the building blocks out of which -the Tcl event notifier is constructed. The event notifier is the lowest -layer in the Tcl event mechanism. It consists of three things: -.IP [1] -Event sources: these represent the ways in which events can be -generated. For example, there is a timer event source that implements -the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR -command, and there is a file event source that implements the -\fBTcl_CreateFileHandler\fR procedure on Unix systems. An event -source must work with the notifier to detect events at the right -times, record them on the event queue, and eventually notify -higher-level software that they have occurred. The procedures -\fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR, -and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and -\fBTcl_DeleteEvents\fR are used primarily by event sources. -.IP [2] -The event queue: for non-threaded applications, -there is a single queue for the whole application, -containing events that have been detected but not yet serviced. Event -sources place events onto the queue so that they may be processed in -order at appropriate times during the event loop. The event queue -guarantees a fair discipline of event handling, so that no event -source can starve the others. It also allows events to be saved for -servicing at a future time. Threaded applications work in a -similar manner, except that there is a separate event queue for -each thread containing a Tcl interpreter. -\fBTcl_QueueEvent\fR is used (primarily -by event sources) to add events to the event queue and -\fBTcl_DeleteEvents\fR is used to remove events from the queue without -processing them. In a threaded application, \fBTcl_QueueEvent\fR adds -an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR -adds an event to a queue in a specific thread. -.IP [3] -The event loop: in order to detect and process events, the application -enters a loop that waits for events to occur, places them on the event -queue, and then processes them. Most applications will do this by -calling the procedure \fBTcl_DoOneEvent\fR, which is described in a -separate manual entry. -.PP -Most Tcl applications need not worry about any of the internals of -the Tcl notifier. However, the notifier now has enough flexibility -to be retargeted either for a new platform or to use an external event -loop (such as the Motif event loop, when Tcl is embedded in a Motif -application). The procedures \fBTcl_WaitForEvent\fR and -\fBTcl_SetTimer\fR are normally implemented by Tcl, but may be -replaced with new versions to retarget the notifier (the -\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, -\fBTcl_FinalizeNotifier\fR, \fBTcl_Sleep\fR, -\fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must -also be replaced; see CREATING A NEW NOTIFIER below for details). -The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR, -\fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided -to help connect Tcl's event loop to an external event loop such as -Motif's. -.SH "NOTIFIER BASICS" -.PP -The easiest way to understand how the notifier works is to consider -what happens when \fBTcl_DoOneEvent\fR is called. -\fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates -what sort of events it is OK to process and also whether or not to -block if no events are ready. \fBTcl_DoOneEvent\fR does the following -things: -.IP [1] -Check the event queue to see if it contains any events that can -be serviced. If so, service the first possible event, remove it -from the queue, and return. It does this by calling -\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument. -.IP [2] -Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR -invokes a \fIsetup procedure\fR in each event source. -The event source will perform event-source specific initialization and -possibly call \fBTcl_SetMaxBlockTime\fR to limit how long -\fBTcl_WaitForEvent\fR will block if no new events occur. -.IP [3] -Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently -on different platforms; it waits for an event to occur, based on the -information provided by the event sources. -It may cause the application to block if \fItimePtr\fR specifies -an interval other than 0. -\fBTcl_WaitForEvent\fR returns when something has happened, -such as a file becoming readable or the interval given by \fItimePtr\fR -expiring. If there are no events for \fBTcl_WaitForEvent\fR to -wait for, so that it would block forever, then it returns immediately -and \fBTcl_DoOneEvent\fR returns 0. -.IP [4] -Call a \fIcheck procedure\fR in each event source. The check -procedure determines whether any events of interest to this source -occurred. If so, the events are added to the event queue. -.IP [5] -Check the event queue to see if it contains any events that can -be serviced. If so, service the first possible event, remove it -from the queue, and return. -.IP [6] -See if there are idle callbacks pending. If so, invoke all of them and -return. -.IP [7] -Either return 0 to indicate that no events were ready, or go back to -step [2] if blocking was requested by the caller. -.SH "CREATING A NEW EVENT SOURCE" -.PP -An event source consists of three procedures invoked by the notifier, -plus additional C procedures that are invoked by higher-level code -to arrange for event-driven callbacks. The three procedures called -by the notifier consist of the setup and check procedures described -above, plus an additional procedure that is invoked when an event -is removed from the event queue for servicing. -.PP -The procedure \fBTcl_CreateEventSource\fR creates a new event source. -Its arguments specify the setup procedure and check procedure for -the event source. -\fISetupProc\fR should match the following prototype: -.PP -.CS -typedef void \fBTcl_EventSetupProc\fR( - ClientData \fIclientData\fR, - int \fIflags\fR); -.CE -.PP -The \fIclientData\fR argument will be the same as the \fIclientData\fR -argument to \fBTcl_CreateEventSource\fR; it is typically used to -point to private information managed by the event source. -The \fIflags\fR argument will be the same as the \fIflags\fR -argument passed to \fBTcl_DoOneEvent\fR except that it will never -be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR). -\fIFlags\fR indicates what kinds of events should be considered; -if the bit corresponding to this event source is not set, the event -source should return immediately without doing anything. For -example, the file event source checks for the \fBTCL_FILE_EVENTS\fR -bit. -.PP -\fISetupProc\fR's job is to make sure that the application wakes up -when events of the desired type occur. This is typically done in a -platform-dependent fashion. For example, under Unix an event source -might call \fBTcl_CreateFileHandler\fR; under Windows it might -request notification with a Windows event. For timer-driven event -sources such as timer events or any polled event, the event source -can call \fBTcl_SetMaxBlockTime\fR to force the application to wake -up after a specified time even if no events have occurred. -If no event source calls \fBTcl_SetMaxBlockTime\fR -then \fBTcl_WaitForEvent\fR will wait as long as necessary for an -event to occur; otherwise, it will only wait as long as the shortest -interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event -sources. If an event source knows that it already has events ready to -report, it can request a zero maximum block time. For example, the -setup procedure for the X event source looks to see if there are -events already queued. If there are, it calls -\fBTcl_SetMaxBlockTime\fR with a 0 block time so that -\fBTcl_WaitForEvent\fR does not block if there is no new data on the X -connection. -The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to -a structure that describes a time interval in seconds and -microseconds: -.PP -.CS -typedef struct Tcl_Time { - long \fIsec\fR; - long \fIusec\fR; -} \fBTcl_Time\fR; -.CE -.PP -The \fIusec\fR field should be less than 1000000. -.PP -Information provided to \fBTcl_SetMaxBlockTime\fR -is only used for the next call to \fBTcl_WaitForEvent\fR; it is -discarded after \fBTcl_WaitForEvent\fR returns. -The next time an event wait is done each of the event sources' -setup procedures will be called again, and they can specify new -information for that event wait. -.PP -If the application uses an external event loop rather than -\fBTcl_DoOneEvent\fR, the event sources may need to call -\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event -handler is registered that needs to poll for events, the event source -may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to -force the external event loop to call Tcl. In this case, -\fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest -interval seen since the last call to \fBTcl_DoOneEvent\fR or -\fBTcl_ServiceAll\fR. -.PP -In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other -platform-specific procedures may also be available for -\fIsetupProc\fR, if there is additional information needed by -\fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems -the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events. -.PP -The second procedure provided by each event source is its check -procedure, indicated by the \fIcheckProc\fR argument to -\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the -following prototype: -.PP -.CS -typedef void \fBTcl_EventCheckProc\fR( - ClientData \fIclientData\fR, - int \fIflags\fR); -.CE -.PP -The arguments to this procedure are the same as those for \fIsetupProc\fR. -\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited -for events. Presumably at least one event source is now prepared to -queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources -in turn, so they all have a chance to queue any events that are ready. -The check procedure does two things. First, it must see if any events -have triggered. Different event sources do this in different ways. -.PP -If an event source's check procedure detects an interesting event, it -must add the event to Tcl's event queue. To do this, the event source -calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to -a dynamically allocated structure containing the event (see below for -more information on memory management issues). Each event source can -define its own event structure with whatever information is relevant -to that event source. However, the first element of the structure -must be a structure of type \fBTcl_Event\fR, and the address of this -structure is used when communicating between the event source and the -rest of the notifier. A \fBTcl_Event\fR has the following definition: -.PP -.CS -typedef struct { - Tcl_EventProc *\fIproc\fR; - struct Tcl_Event *\fInextPtr\fR; -} \fBTcl_Event\fR; -.CE -.PP -The event source must fill in the \fIproc\fR field of -the event before calling \fBTcl_QueueEvent\fR. -The \fInextPtr\fR is used to link together the events in the queue -and should not be modified by the event source. -.PP -An event may be added to the queue at any of three positions, depending -on the \fIposition\fR argument to \fBTcl_QueueEvent\fR: -.IP \fBTCL_QUEUE_TAIL\fR 24 -Add the event at the back of the queue, so that all other pending -events will be serviced first. This is almost always the right -place for new events. -.IP \fBTCL_QUEUE_HEAD\fR 24 -Add the event at the front of the queue, so that it will be serviced -before all other queued events. -.IP \fBTCL_QUEUE_MARK\fR 24 -Add the event at the front of the queue, unless there are other -events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so, -add the new event just after all other \fBTCL_QUEUE_MARK\fR events. -This value of \fIposition\fR is used to insert an ordered sequence of -events at the front of the queue, such as a series of -Enter and Leave events synthesized during a grab or ungrab operation -in Tk. -.PP -When it is time to handle an event from the queue (steps 1 and 4 -above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified -in the first queued \fBTcl_Event\fR structure. -\fIProc\fR must match the following prototype: -.PP -.CS -typedef int \fBTcl_EventProc\fR( - Tcl_Event *\fIevPtr\fR, - int \fIflags\fR); -.CE -.PP -The first argument to \fIproc\fR is a pointer to the event, which will -be the same as the first argument to the \fBTcl_QueueEvent\fR call that -added the event to the queue. -The second argument to \fIproc\fR is the \fIflags\fR argument for the -current call to \fBTcl_ServiceEvent\fR; this is used by the event source -to return immediately if its events are not relevant. -.PP -It is up to \fIproc\fR to handle the event, typically by invoking -one or more Tcl commands or C-level callbacks. -Once the event source has finished handling the event it returns 1 -to indicate that the event can be removed from the queue. -If for some reason the event source decides that the event cannot -be handled at this time, it may return 0 to indicate that the event -should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR -will go on to the next event in the queue and attempt to service it. -There are several reasons why an event source might defer an event. -One possibility is that events of this type are excluded by the -\fIflags\fR argument. -For example, the file event source will always return 0 if the -\fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR. -Another example of deferring events happens in Tk if -\fBTk_RestrictEvents\fR has been invoked to defer certain kinds -of window events. -.PP -When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the -event from the event queue and free its storage. -Note that the storage for an event must be allocated by -the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR) -before calling \fBTcl_QueueEvent\fR, but it -will be freed by \fBTcl_ServiceEvent\fR, not by the event source. -.PP -Threaded applications work in a -similar manner, except that there is a separate event queue for -each thread containing a Tcl interpreter. -Calling \fBTcl_QueueEvent\fR in a multithreaded application adds -an event to the current thread's queue. -To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR. -\fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument, -which uniquely identifies a thread in a Tcl application. To obtain the -Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR -procedure. (A thread would then need to pass this identifier to other -threads for those threads to be able to add events to its queue.) -After adding an event to another thread's queue, you then typically -need to call \fBTcl_ThreadAlert\fR to -.QW "wake up" -that thread's notifier to alert it to the new event. -.PP -\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more -events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR -for each event in the queue, deleting those for with the procedure -returns 1. Events for which the procedure returns 0 are left in the -queue. \fIProc\fR should match the following prototype: -.PP -.CS -typedef int \fBTcl_EventDeleteProc\fR( - Tcl_Event *\fIevPtr\fR, - ClientData \fIclientData\fR); -.CE -.PP -The \fIclientData\fR argument will be the same as the \fIclientData\fR -argument to \fBTcl_DeleteEvents\fR; it is typically used to point to -private information managed by the event source. The \fIevPtr\fR will -point to the next event in the queue. -.PP -\fBTcl_DeleteEventSource\fR deletes an event source. The \fIsetupProc\fR, -\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those -provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted. -If no such source exists, \fBTcl_DeleteEventSource\fR has no effect. -.SH "CREATING A NEW NOTIFIER" -.PP -The notifier consists of all the procedures described in this manual -entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are -available on all platforms, and \fBTcl_CreateFileHandler\fR and -\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these -procedures are generic, in that they are the same for all notifiers. -However, none of the procedures are notifier-dependent: -\fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, -\fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, -\fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR, -\fBTcl_DeleteFileHandler\fR and \fBTcl_ServiceModeHook\fR. To support a -new platform or to integrate Tcl with an application-specific event loop, -you must write new versions of these procedures. -.PP -\fBTcl_InitNotifier\fR initializes the notifier state and returns -a handle to the notifier state. Tcl calls this -procedure when initializing a Tcl interpreter. Similarly, -\fBTcl_FinalizeNotifier\fR shuts down the notifier, and is -called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter. -.PP -\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier; -it is responsible for waiting for an -.QW interesting -event to occur or -for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked, -each of the event sources' setup procedure will have been invoked. -The \fItimePtr\fR argument to -\fBTcl_WaitForEvent\fR gives the maximum time to block for an event, -based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures -and on other information (such as the \fBTCL_DONT_WAIT\fR bit in -\fIflags\fR). -.PP -Ideally, \fBTcl_WaitForEvent\fR should only wait for an event -to occur; it should not actually process the event in any way. -Later on, the -event sources will process the raw events and create Tcl_Events on -the event queue in their \fIcheckProc\fR procedures. -However, on some platforms (such as Windows) this is not possible; -events may be processed in \fBTcl_WaitForEvent\fR, including queuing -Tcl_Events and more (for example, callbacks for native widgets may be -invoked). The return value from \fBTcl_WaitForEvent\fR must be either -0, 1, or \-1. On platforms such as Windows where events get processed in -\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more -events still pending that have not been processed. This is a sign to the -caller that it must call \fBTcl_WaitForEvent\fR again if it wants all -pending events to be processed. A 0 return value means that calling -\fBTcl_WaitForEvent\fR again will not have any effect: either this is a -platform where \fBTcl_WaitForEvent\fR only waits without doing any event -processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no -additional events to process (e.g. it returned because the time -elapsed). Finally, a return value of \-1 means that the event loop is -no longer operational and the application should probably unwind and -terminate. Under Windows this happens when a WM_QUIT message is received; -under Unix it happens when \fBTcl_WaitForEvent\fR would have waited -forever because there were no active event sources and the timeout was -infinite. -.PP -\fBTcl_AlertNotifier\fR is used in multithreaded applications to allow -any thread to -.QW "wake up" -the notifier to alert it to new events on its -queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier -handle returned by \fBTcl_InitNotifier\fR. -.PP -If the notifier will be used with an external event loop, then it must -also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is -invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking -time has been reduced. \fBTcl_SetTimer\fR should arrange for the -external event loop to invoke \fBTcl_ServiceAll\fR after the specified -interval even if no events have occurred. This interface is needed -because \fBTcl_WaitForEvent\fR is not invoked when there is an external -event loop. If the -notifier will only be used from \fBTcl_DoOneEvent\fR, then -\fBTcl_SetTimer\fR need not do anything. -.PP -\fBTcl_ServiceModeHook\fR is called by the platform-independent portion -of the notifier when client code makes a call to -\fBTcl_SetServiceMode\fR. This hook is provided to support operating -systems that require special event handling when the application is in -a modal loop (the Windows notifier, for instance, uses this hook to -create a communication window). -.PP -On Unix systems, the file event source also needs support from the -notifier. The file event source consists of the -\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR -procedures, which are described in the \fBTcl_CreateFileHandler\fR -manual page. -.PP -The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described -in their respective manual pages. -.PP -The easiest way to create a new notifier is to look at the code -for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR -or \fBwin/tclWinNotify.c\fR in the Tcl source distribution. -.SH "REPLACING THE NOTIFIER" -.PP -A notifier that has been written according to the conventions above -can also be installed in a running process in place of the standard -notifier. This mechanism is used so that a single executable can be -used (with the standard notifier) as a stand-alone program and reused -(with a replacement notifier in a loadable extension) as an extension -to another program, such as a Web browser plugin. -.PP -To do this, the extension makes a call to \fBTcl_SetNotifier\fR -passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The -structure has the following layout: -.PP -.CS -typedef struct Tcl_NotifierProcs { - Tcl_SetTimerProc *\fIsetTimerProc\fR; - Tcl_WaitForEventProc *\fIwaitForEventProc\fR; - Tcl_CreateFileHandlerProc *\fIcreateFileHandlerProc\fR; - Tcl_DeleteFileHandlerProc *\fIdeleteFileHandlerProc\fR; - Tcl_InitNotifierProc *\fIinitNotifierProc\fR; - Tcl_FinalizeNotifierProc *\fIfinalizeNotifierProc\fR; - Tcl_AlertNotifierProc *\fIalertNotifierProc\fR; - Tcl_ServiceModeHookProc *\fIserviceModeHookProc\fR; -} \fBTcl_NotifierProcs\fR; -.CE -.PP -Following the call to \fBTcl_SetNotifier\fR, the pointers given in -the \fBTcl_NotifierProcs\fR structure replace whatever notifier had -been installed in the process. -.PP -It is extraordinarily unwise to replace a running notifier. Normally, -\fBTcl_SetNotifier\fR should be called at process initialization time -before the first call to \fBTcl_InitNotifier\fR. -.SH "EXTERNAL EVENT LOOPS" -.PP -The notifier interfaces are designed so that Tcl can be embedded into -applications that have their own private event loops. In this case, -the application does not call \fBTcl_DoOneEvent\fR except in the case -of recursive event loops such as calls to the Tcl commands \fBupdate\fR -or \fBvwait\fR. Most of the time is spent in the external event loop -of the application. In this case the notifier must arrange for the -external event loop to call back into Tcl when something -happens on the various Tcl event sources. These callbacks should -arrange for appropriate Tcl events to be placed on the Tcl event queue. -.PP -Because the external event loop is not calling \fBTcl_DoOneEvent\fR on -a regular basis, it is up to the notifier to arrange for -\fBTcl_ServiceEvent\fR to be called whenever events are pending on the -Tcl event queue. The easiest way to do this is to invoke -\fBTcl_ServiceAll\fR at the end of each callback from the external -event loop. This will ensure that all of the event sources are -polled, any queued events are serviced, and any pending idle handlers -are processed before returning control to the application. In -addition, event sources that need to poll for events can call -\fBTcl_SetMaxBlockTime\fR to force the external event loop to call -Tcl even if no events are available on the system event queue. -.PP -As a side effect of processing events detected in the main external -event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event -loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke -the external event loop, which will result in callbacks as described -in the preceding paragraph, which will result in calls to -\fBTcl_ServiceAll\fR. However, in these cases it is undesirable to -service events in \fBTcl_ServiceAll\fR. Servicing events there is -unnecessary because control will immediately return to the -external event loop and hence to \fBTcl_DoOneEvent\fR, which can -service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is -supposed to service only a single event, whereas \fBTcl_ServiceAll\fR -normally services all pending events. To handle this situation, -\fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR -that causes it to return without servicing any events. -This flag is called the \fIservice mode\fR; -\fBTcl_DoOneEvent\fR restores it to its previous value before it returns. -.PP -In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR -to service events -even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens -when there is yet another recursive event loop invoked via an -event handler called by \fBTcl_DoOneEvent\fR (such as one that is -part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not -have a chance to service events so \fBTcl_ServiceAll\fR must service -them all. Any recursive event loop that calls an external event -loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so -that all events get processed in \fBTcl_ServiceAll\fR. This is done -by invoking the \fBTcl_SetServiceMode\fR procedure. If -\fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls -to \fBTcl_ServiceAll\fR will return immediately without processing any -events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR, -then calls to \fBTcl_ServiceAll\fR will behave normally. -\fBTcl_SetServiceMode\fR returns the previous value of the service -mode, which should be restored when the recursive loop exits. -\fBTcl_GetServiceMode\fR returns the current value of the service -mode. -.SH "SEE ALSO" -Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3), -Tcl_DoOneEvent(3), Thread(3) -.SH KEYWORDS -event, notifier, event queue, event sources, file events, timer, idle, service mode, threads |