2 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP type name in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is type of argument (int, etc.), in/out is either "in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 '\" needed; use .AS below instead)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages. The first argument is ignored and used for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found and removed when they reach a certain age. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
249 Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
253 \fB#include <tcl.h>\fR
255 \fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
257 \fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
259 \fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
261 \fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
264 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
267 \fBTcl_WaitForEvent\fR(\fItimePtr\fR)
269 \fBTcl_SetTimer\fR(\fItimePtr\fR)
272 \fBTcl_ServiceAll\fR()
275 \fBTcl_ServiceEvent\fR(\fIflags\fR)
278 \fBTcl_GetServiceMode\fR()
281 \fBTcl_SetServiceMode\fR(\fImode\fR)
285 .AS Tcl_EventDeleteProc milliseconds
286 .AS Tcl_EventSetupProc *setupProc
287 .AP Tcl_EventSetupProc *setupProc in
288 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
289 .AP Tcl_EventCheckProc *checkProc in
290 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
291 events. Checks to see if any events have occurred and, if so,
293 .AP ClientData clientData in
294 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
296 .AP Tcl_Time *timePtr in
297 Indicates the maximum amount of time to wait for an event. This
298 is specified as an interval (how long to wait), not an absolute
299 time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
300 is NULL, it means there is no maximum wait time: wait forever if
302 .AP Tcl_Event *evPtr in
303 An event to add to the event queue. The storage for the event must
304 have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
305 .AP Tcl_QueuePosition position in
306 Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
307 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
309 What types of events to service. These flags are the same as those
310 passed to \fBTcl_DoOneEvent\fR.
311 .AP Tcl_EventDeleteProc *deleteProc in
312 Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
315 Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
316 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
323 The interfaces described here are used to customize the Tcl event
324 loop. The two most common customizations are to add new sources of
325 events and to merge Tcl's event loop with some other event loop, such
326 as one provided by an application in which Tcl is embedded. Each of
327 these tasks is described in a separate section below.
330 The procedures in this manual entry are the building blocks out of which
331 the Tcl event notifier is constructed. The event notifier is the lowest
332 layer in the Tcl event mechanism. It consists of three things:
334 Event sources: these represent the ways in which events can be
335 generated. For example, there is a timer event source that implements
336 the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
337 command, and there is a file event source that implements the
338 \fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
339 source must work with the notifier to detect events at the right
340 times, record them on the event queue, and eventually notify
341 higher-level software that they have occurred. The procedures
342 \fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
343 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
344 \fBTcl_DeleteEvents\fR are used primarily by event sources.
346 The event queue: there is a single queue for the whole application,
347 containing events that have been detected but not yet serviced. Event
348 sources place events onto the queue so that they may be processed in
349 order at appropriate times during the event loop. The event queue
350 guarantees a fair discipline of event handling, so that no event
351 source can starve the others. It also allows events to be saved for
352 servicing at a future time.
354 \fBTcl_QueueEvent\fR is used (primarily
355 by event sources) to add events to the event queue and
356 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
359 The event loop: in order to detect and process events, the application
360 enters a loop that waits for events to occur, places them on the event
361 queue, and then processes them. Most applications will do this by
362 calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
363 separate manual entry.
365 Most Tcl applications need not worry about any of the internals of
366 the Tcl notifier. However, the notifier now has enough flexibility
367 to be retargeted either for a new platform or to use an external event
368 loop (such as the Motif event loop, when Tcl is embedded in a Motif
369 application). The procedures \fBTcl_WaitForEvent\fR and
370 \fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
371 replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
372 \fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
373 also be replaced; see CREATING A NEW NOTIFIER below for details).
374 The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
375 \fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
376 to help connect Tcl's event loop to an external event loop such as
378 .SH "NOTIFIER BASICS"
381 The easiest way to understand how the notifier works is to consider
382 what happens when \fBTcl_DoOneEvent\fR is called.
383 \fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
384 what sort of events it is OK to process and also whether or not to
385 block if no events are ready. \fBTcl_DoOneEvent\fR does the following
388 Check the event queue to see if it contains any events that can
389 be serviced. If so, service the first possible event, remove it
391 from the queue, and return. It does this by calling
392 \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
395 Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
396 invokes a \fIsetup procedure\fR in each event source.
397 The event source will perform event-source specific initialization and
399 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
401 \fBTcl_WaitForEvent\fR will block if no new events occur.
403 Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
404 on different platforms; it waits for an event to occur, based on the
405 information provided by the event sources.
406 It may cause the application to block if \fItimePtr\fR specifies
407 an interval other than 0.
408 \fBTcl_WaitForEvent\fR returns when something has happened,
409 such as a file becoming readable or the interval given by \fItimePtr\fR
410 expiring. If there are no events for \fBTcl_WaitForEvent\fR to
411 wait for, so that it would block forever, then it returns immediately
412 and \fBTcl_DoOneEvent\fR returns 0.
414 Call a \fIcheck procedure\fR in each event source. The check
415 procedure determines whether any events of interest to this source
416 occurred. If so, the events are added to the event queue.
418 Check the event queue to see if it contains any events that can
419 be serviced. If so, service the first possible event, remove it
420 from the queue, and return.
422 See if there are idle callbacks pending. If so, invoke all of them and
425 Either return 0 to indicate that no events were ready, or go back to
426 step [2] if blocking was requested by the caller.
428 .SH "CREATING A NEW EVENT SOURCE"
430 An event source consists of three procedures invoked by the notifier,
431 plus additional C procedures that are invoked by higher-level code
432 to arrange for event-driven callbacks. The three procedures called
433 by the notifier consist of the setup and check procedures described
434 above, plus an additional procedure that is invoked when an event
435 is removed from the event queue for servicing.
437 The procedure \fBTcl_CreateEventSource\fR creates a new event source.
438 Its arguments specify the setup procedure and check procedure for
440 \fISetupProc\fR should match the following prototype:
442 typedef void Tcl_EventSetupProc(
443 ClientData \fIclientData\fR,
446 The \fIclientData\fR argument will be the same as the \fIclientData\fR
447 argument to \fBTcl_CreateEventSource\fR; it is typically used to
448 point to private information managed by the event source.
449 The \fIflags\fR argument will be the same as the \fIflags\fR
450 argument passed to \fBTcl_DoOneEvent\fR except that it will never
451 be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
452 \fIFlags\fR indicates what kinds of events should be considered;
453 if the bit corresponding to this event source isn't set, the event
454 source should return immediately without doing anything. For
455 example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
458 \fISetupProc\fR's job is to make sure that the application wakes up
459 when events of the desired type occur. This is typically done in a
460 platform-dependent fashion. For example, under Unix an event source
461 might call \fBTcl_CreateFileHandler\fR; under Windows it might
462 request notification with a Windows event. For timer-driven event
463 sources such as timer events or any polled event, the event source
464 can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
465 up after a specified time even if no events have occurred.
467 If no event source calls \fBTcl_SetMaxBlockTime\fR
468 then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
469 event to occur; otherwise, it will only wait as long as the shortest
470 interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
471 sources. If an event source knows that it already has events ready to
472 report, it can request a zero maximum block time. For example, the
473 setup procedure for the X event source looks to see if there are
474 events already queued. If there are, it calls
475 \fBTcl_SetMaxBlockTime\fR with a 0 block time so that
476 \fBTcl_WaitForEvent\fR does not block if there is no new data on the X
479 The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
480 a structure that describes a time interval in seconds and
483 typedef struct Tcl_Time {
488 The \fIusec\fR field should be less than 1000000.
491 Information provided to \fBTcl_SetMaxBlockTime\fR
492 is only used for the next call to \fBTcl_WaitForEvent\fR; it is
493 discarded after \fBTcl_WaitForEvent\fR returns.
495 The next time an event wait is done each of the event sources'
496 setup procedures will be called again, and they can specify new
497 information for that event wait.
500 If the application uses an external event loop rather than
501 \fBTcl_DoOneEvent\fR, the event sources may need to call
502 \fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
503 handler is registered that needs to poll for events, the event source
504 may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
505 force the external event loop to call Tcl. In this case,
506 \fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
507 interval seen since the last call to \fBTcl_DoOneEvent\fR or
508 \fBTcl_ServiceAll\fR.
510 In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
511 platform-specific procedures may also be available for
512 \fIsetupProc\fR, if there is additional information needed by
513 \fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
514 the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
517 The second procedure provided by each event source is its check
518 procedure, indicated by the \fIcheckProc\fR argument to
519 \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
522 typedef void Tcl_EventCheckProc(
523 ClientData \fIclientData\fR,
526 The arguments to this procedure are the same as those for \fIsetupProc\fR.
527 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
528 for events. Presumably at least one event source is now prepared to
529 queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
530 in turn, so they all have a chance to queue any events that are ready.
531 The check procedure does two things. First, it must see if any events
532 have triggered. Different event sources do this in different ways.
534 If an event source's check procedure detects an interesting event, it
535 must add the event to Tcl's event queue. To do this, the event source
536 calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
537 a dynamically allocated structure containing the event (see below for
538 more information on memory management issues). Each event source can
539 define its own event structure with whatever information is relevant
540 to that event source. However, the first element of the structure
541 must be a structure of type \fBTcl_Event\fR, and the address of this
542 structure is used when communicating between the event source and the
543 rest of the notifier. A \fBTcl_Event\fR has the following definition:
545 typedef struct Tcl_Event {
546 Tcl_EventProc *\fIproc\fR;
547 struct Tcl_Event *\fInextPtr\fR;
550 The event source must fill in the \fIproc\fR field of
551 the event before calling \fBTcl_QueueEvent\fR.
552 The \fInextPtr\fR is used to link together the events in the queue
553 and should not be modified by the event source.
555 An event may be added to the queue at any of three positions, depending
556 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
557 .IP \fBTCL_QUEUE_TAIL\fR 24
558 Add the event at the back of the queue, so that all other pending
559 events will be serviced first. This is almost always the right
560 place for new events.
561 .IP \fBTCL_QUEUE_HEAD\fR 24
562 Add the event at the front of the queue, so that it will be serviced
563 before all other queued events.
564 .IP \fBTCL_QUEUE_MARK\fR 24
565 Add the event at the front of the queue, unless there are other
566 events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
567 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
568 This value of \fIposition\fR is used to insert an ordered sequence of
569 events at the front of the queue, such as a series of
570 Enter and Leave events synthesized during a grab or ungrab operation
574 When it is time to handle an event from the queue (steps 1 and 4
575 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
577 in the first queued \fBTcl_Event\fR structure.
578 \fIProc\fR must match the following prototype:
580 typedef int Tcl_EventProc(
581 Tcl_Event *\fIevPtr\fR,
584 The first argument to \fIproc\fR is a pointer to the event, which will
585 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
586 added the event to the queue.
587 The second argument to \fIproc\fR is the \fIflags\fR argument for the
589 current call to \fBTcl_ServiceEvent\fR; this is used by the event source
591 to return immediately if its events are not relevant.
593 It is up to \fIproc\fR to handle the event, typically by invoking
594 one or more Tcl commands or C-level callbacks.
595 Once the event source has finished handling the event it returns 1
596 to indicate that the event can be removed from the queue.
597 If for some reason the event source decides that the event cannot
598 be handled at this time, it may return 0 to indicate that the event
600 should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
602 will go on to the next event in the queue and attempt to service it.
603 There are several reasons why an event source might defer an event.
604 One possibility is that events of this type are excluded by the
605 \fIflags\fR argument.
606 For example, the file event source will always return 0 if the
607 \fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
608 Another example of deferring events happens in Tk if
609 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
613 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
614 event from the event queue and free its storage.
615 Note that the storage for an event must be allocated by
616 the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
617 before calling \fBTcl_QueueEvent\fR, but it
618 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
620 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
621 events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
622 for each event in the queue, deleting those for with the procedure
623 returns 1. Events for which the procedure returns 0 are left in the
624 queue. \fIProc\fR should match the following prototype:
626 typedef int Tcl_EventDeleteProc(
627 Tcl_Event *\fIevPtr\fR,
628 ClientData \fIclientData\fR);
630 The \fIclientData\fR argument will be the same as the \fIclientData\fR
631 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
632 private information managed by the event source. The \fIevPtr\fR will
633 point to the next event in the queue.
636 .SH "CREATING A NEW NOTIFIER"
638 The notifier consists of all the procedures described in this manual
639 entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
641 available on all platforms, and \fBTcl_CreateFileHandler\fR and
642 \fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
643 procedures are generic, in that they are the same for all notifiers.
644 However, five of the procedures are notifier-dependent:
645 \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
646 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
647 support a new platform or to integrate Tcl with an
648 application-specific event loop, you must write new versions of these
651 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
652 it is responsible for waiting for an ``interesting'' event to occur or
653 for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
654 each of the event sources' setup procedure will have been invoked.
655 The \fItimePtr\fR argument to
656 \fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
657 based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
658 and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
661 Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
662 to occur; it should not actually process the event in any way.
664 event sources will process the raw events and create Tcl_Events on
665 the event queue in their \fIcheckProc\fR procedures.
666 However, on some platforms (such as Windows) this isn't possible;
667 events may be processed in \fBTcl_WaitForEvent\fR, including queuing
668 Tcl_Events and more (for example, callbacks for native widgets may be
669 invoked). The return value from \fBTcl_WaitForEvent\fR must be either
670 0, 1, or \-1. On platforms such as Windows where events get processed in
671 \fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
672 events still pending that haven't been processed. This is a sign to the
673 caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
674 pending events to be processed. A 0 return value means that calling
675 \fBTcl_WaitForEvent\fR again will not have any effect: either this is a
676 platform where \fBTcl_WaitForEvent\fR only waits without doing any event
677 processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
678 additional events to process (e.g. it returned because the time
679 elapsed). Finally, a return value of \-1 means that the event loop is
680 no longer operational and the application should probably unwind and
681 terminate. Under Windows this happens when a WM_QUIT message is received;
682 under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
683 forever because there were no active event sources and the timeout was
686 If the notifier will be used with an external event loop, then it must
687 also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
688 invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
689 time has been reduced. \fBTcl_SetTimer\fR should arrange for the
690 external event loop to invoke \fBTcl_ServiceAll\fR after the specified
691 interval even if no events have occurred. This interface is needed
692 because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
694 notifier will only be used from \fBTcl_DoOneEvent\fR, then
695 \fBTcl_SetTimer\fR need not do anything.
697 On Unix systems, the file event source also needs support from the
698 notifier. The file event source consists of the
699 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
700 procedures, which are described elsewhere.
702 The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
705 The easiest way to create a new notifier is to look at the code
706 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
707 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
709 .SH "EXTERNAL EVENT LOOPS"
711 The notifier interfaces are designed so that Tcl can be embedded into
712 applications that have their own private event loops. In this case,
713 the application does not call \fBTcl_DoOneEvent\fR except in the case
714 of recursive event loops such as calls to the Tcl commands \fBupdate\fR
715 or \fBvwait\fR. Most of the time is spent in the external event loop
716 of the application. In this case the notifier must arrange for the
717 external event loop to call back into Tcl when something
718 happens on the various Tcl event sources. These callbacks should
719 arrange for appropriate Tcl events to be placed on the Tcl event queue.
721 Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
722 a regular basis, it is up to the notifier to arrange for
723 \fBTcl_ServiceEvent\fR to be called whenever events are pending on the
724 Tcl event queue. The easiest way to do this is to invoke
725 \fBTcl_ServiceAll\fR at the end of each callback from the external
726 event loop. This will ensure that all of the event sources are
727 polled, any queued events are serviced, and any pending idle handlers
728 are processed before returning control to the application. In
729 addition, event sources that need to poll for events can call
730 \fBTcl_SetMaxBlockTime\fR to force the external event loop to call
731 Tcl even if no events are available on the system event queue.
733 As a side effect of processing events detected in the main external
734 event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
735 loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
736 the external event loop, which will result in callbacks as described
737 in the preceding paragraph, which will result in calls to
738 \fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
739 service events in \fBTcl_ServiceAll\fR. Servicing events there is
740 unnecessary because control will immediately return to the
741 external event loop and hence to \fBTcl_DoOneEvent\fR, which can
742 service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
743 supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
744 normally services all pending events. To handle this situation,
745 \fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
746 that causes it to return without servicing any events.
747 This flag is called the \fIservice mode\fR;
748 \fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
750 In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
752 even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
753 when there is yet another recursive event loop invoked via an
754 event handler called by \fBTcl_DoOneEvent\fR (such as one that is
755 part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
756 have a chance to service events so \fBTcl_ServiceAll\fR must service
757 them all. Any recursive event loop that calls an external event
758 loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
759 that all events get processed in \fBTcl_ServiceAll\fR. This is done
760 by invoking the \fBTcl_SetServiceMode\fR procedure. If
761 \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
762 to \fBTcl_ServiceAll\fR will return immediately without processing any
763 events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
764 then calls to \fBTcl_ServiceAll\fR will behave normally.
765 \fBTcl_SetServiceMode\fR returns the previous value of the service
766 mode, which should be restored when the recursive loop exits.
767 \fBTcl_GetServiceMode\fR returns the current value of the service
772 event, notifier, event queue, event sources, file events, timer, idle, service mode
OSDN Git Service
