2 '\" Copyright (c) 1998-1999 Scriptics Corporation
3 '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 '\" RCS: @(#) $Id: Notifier.3,v 1.9 2002/07/01 18:24:39 jenglish Exp $
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or "in/out" to describe whether procedure reads or modifies arg,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
21 '\" Give maximum sizes of arguments for setting tab stops. Type and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to .AP later. If args are omitted, default tab stops are used.
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
30 '\" End of box enclosure.
33 '\" Begin code excerpt.
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar, for use in marking newly-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version when the .VS was added, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present, then a line break is forced before starting the sidebar.
46 '\" End of vertical sidebar.
49 '\" Begin an indented unfilled display.
52 '\" End of indented unfilled display.
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
60 '\" End of list of standard options for a Tk widget.
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
69 '\" Print arg1 underlined, then print arg2 normally.
71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
77 '\" # Start an argument description
81 . ie !"\\$2"" .TP \\n()Cu
86 \&\\$1 \\fI\\$2\\fP (\\$3)
99 '\" # define tabbing values for .AP
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
118 .if n \l'\\n(.lu\(ul'
121 '\" # BE - end boxed text (draw box now)
126 .ie n \l'\\n(^lu\(ul'
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
147 .ie n 'mc \s12\(br\s0
150 '\" # VE - end of vertical sidebar
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .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
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
194 '\" # DS - begin display
200 '\" # DE - end display
206 '\" # SO - start of list of standard options
208 .SH "STANDARD OPTIONS"
214 '\" # SE - end of list of standard options
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
238 '\" # CE - end code excerpt
246 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
249 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 \- the event queue and notifier interfaces
252 \fB#include <tcl.h>\fR
255 \fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
258 \fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
261 \fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR)
264 \fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
268 \fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
271 \fBTcl_ThreadAlert\fR(\fIthreadId, clientData\fR)
274 \fBTcl_GetCurrentThread\fR()
277 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
280 \fBTcl_InitNotifier\fR()
283 \fBTcl_FinalizeNotifier\fR(\fIclientData\fR)
286 \fBTcl_WaitForEvent\fR(\fItimePtr\fR)
289 \fBTcl_AlertNotifier\fR(\fIclientData\fR)
292 \fBTcl_SetTimer\fR(\fItimePtr\fR)
295 \fBTcl_ServiceAll\fR()
298 \fBTcl_ServiceEvent\fR(\fIflags\fR)
301 \fBTcl_GetServiceMode\fR()
304 \fBTcl_SetServiceMode\fR(\fImode\fR)
308 .AS Tcl_EventDeleteProc milliseconds
309 .AP Tcl_EventSetupProc *setupProc in
310 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
311 .AP Tcl_EventCheckProc *checkProc in
312 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
313 events. Checks to see if any events have occurred and, if so,
315 .AP ClientData clientData in
316 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
318 .AP Tcl_Time *timePtr in
319 Indicates the maximum amount of time to wait for an event. This
320 is specified as an interval (how long to wait), not an absolute
321 time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
322 is NULL, it means there is no maximum wait time: wait forever if
324 .AP Tcl_Event *evPtr in
325 An event to add to the event queue. The storage for the event must
326 have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
327 .AP Tcl_QueuePosition position in
328 Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
329 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
330 .AP Tcl_ThreadId threadId in
331 A unique identifier for a thread.
332 .AP Tcl_EventDeleteProc *deleteProc in
333 Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
335 What types of events to service. These flags are the same as those
336 passed to \fBTcl_DoOneEvent\fR.
339 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
340 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
346 The interfaces described here are used to customize the Tcl event
347 loop. The two most common customizations are to add new sources of
348 events and to merge Tcl's event loop with some other event loop, such
349 as one provided by an application in which Tcl is embedded. Each of
350 these tasks is described in a separate section below.
352 The procedures in this manual entry are the building blocks out of which
353 the Tcl event notifier is constructed. The event notifier is the lowest
354 layer in the Tcl event mechanism. It consists of three things:
356 Event sources: these represent the ways in which events can be
357 generated. For example, there is a timer event source that implements
358 the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
359 command, and there is a file event source that implements the
360 \fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
361 source must work with the notifier to detect events at the right
362 times, record them on the event queue, and eventually notify
363 higher-level software that they have occurred. The procedures
364 \fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
365 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
366 \fBTcl_DeleteEvents\fR are used primarily by event sources.
368 The event queue: for non-threaded applications,
369 there is a single queue for the whole application,
370 containing events that have been detected but not yet serviced. Event
371 sources place events onto the queue so that they may be processed in
372 order at appropriate times during the event loop. The event queue
373 guarantees a fair discipline of event handling, so that no event
374 source can starve the others. It also allows events to be saved for
375 servicing at a future time.
377 Threaded applications work in a
378 similar manner, except that there is a separate event queue for
379 each thread containing a Tcl interpreter.
380 \fBTcl_QueueEvent\fR is used (primarily
381 by event sources) to add events to the event queue and
382 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
383 processing them. In a threaded application, \fBTcl_QueueEvent\fR adds
384 an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
385 adds an event to a queue in a specific thread.
387 The event loop: in order to detect and process events, the application
388 enters a loop that waits for events to occur, places them on the event
389 queue, and then processes them. Most applications will do this by
390 calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
391 separate manual entry.
393 Most Tcl applications need not worry about any of the internals of
394 the Tcl notifier. However, the notifier now has enough flexibility
395 to be retargeted either for a new platform or to use an external event
396 loop (such as the Motif event loop, when Tcl is embedded in a Motif
397 application). The procedures \fBTcl_WaitForEvent\fR and
398 \fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
399 replaced with new versions to retarget the notifier (the
400 \fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
401 \fBTcl_FinalizeNotifier\fR, \fBTcl_Sleep\fR,
402 \fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
403 also be replaced; see CREATING A NEW NOTIFIER below for details).
404 The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
405 \fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
406 to help connect Tcl's event loop to an external event loop such as
408 .SH "NOTIFIER BASICS"
411 The easiest way to understand how the notifier works is to consider
412 what happens when \fBTcl_DoOneEvent\fR is called.
413 \fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
414 what sort of events it is OK to process and also whether or not to
415 block if no events are ready. \fBTcl_DoOneEvent\fR does the following
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
421 from the queue, and return. It does this by calling
422 \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
425 Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
426 invokes a \fIsetup procedure\fR in each event source.
427 The event source will perform event-source specific initialization and
429 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
431 \fBTcl_WaitForEvent\fR will block if no new events occur.
433 Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
434 on different platforms; it waits for an event to occur, based on the
435 information provided by the event sources.
436 It may cause the application to block if \fItimePtr\fR specifies
437 an interval other than 0.
438 \fBTcl_WaitForEvent\fR returns when something has happened,
439 such as a file becoming readable or the interval given by \fItimePtr\fR
440 expiring. If there are no events for \fBTcl_WaitForEvent\fR to
441 wait for, so that it would block forever, then it returns immediately
442 and \fBTcl_DoOneEvent\fR returns 0.
444 Call a \fIcheck procedure\fR in each event source. The check
445 procedure determines whether any events of interest to this source
446 occurred. If so, the events are added to the event queue.
448 Check the event queue to see if it contains any events that can
449 be serviced. If so, service the first possible event, remove it
450 from the queue, and return.
452 See if there are idle callbacks pending. If so, invoke all of them and
455 Either return 0 to indicate that no events were ready, or go back to
456 step [2] if blocking was requested by the caller.
458 .SH "CREATING A NEW EVENT SOURCE"
460 An event source consists of three procedures invoked by the notifier,
461 plus additional C procedures that are invoked by higher-level code
462 to arrange for event-driven callbacks. The three procedures called
463 by the notifier consist of the setup and check procedures described
464 above, plus an additional procedure that is invoked when an event
465 is removed from the event queue for servicing.
467 The procedure \fBTcl_CreateEventSource\fR creates a new event source.
468 Its arguments specify the setup procedure and check procedure for
470 \fISetupProc\fR should match the following prototype:
472 typedef void Tcl_EventSetupProc(
473 ClientData \fIclientData\fR,
476 The \fIclientData\fR argument will be the same as the \fIclientData\fR
477 argument to \fBTcl_CreateEventSource\fR; it is typically used to
478 point to private information managed by the event source.
479 The \fIflags\fR argument will be the same as the \fIflags\fR
480 argument passed to \fBTcl_DoOneEvent\fR except that it will never
481 be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
482 \fIFlags\fR indicates what kinds of events should be considered;
483 if the bit corresponding to this event source isn't set, the event
484 source should return immediately without doing anything. For
485 example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
488 \fISetupProc\fR's job is to make sure that the application wakes up
489 when events of the desired type occur. This is typically done in a
490 platform-dependent fashion. For example, under Unix an event source
491 might call \fBTcl_CreateFileHandler\fR; under Windows it might
492 request notification with a Windows event. For timer-driven event
493 sources such as timer events or any polled event, the event source
494 can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
495 up after a specified time even if no events have occurred.
497 If no event source calls \fBTcl_SetMaxBlockTime\fR
498 then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
499 event to occur; otherwise, it will only wait as long as the shortest
500 interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
501 sources. If an event source knows that it already has events ready to
502 report, it can request a zero maximum block time. For example, the
503 setup procedure for the X event source looks to see if there are
504 events already queued. If there are, it calls
505 \fBTcl_SetMaxBlockTime\fR with a 0 block time so that
506 \fBTcl_WaitForEvent\fR does not block if there is no new data on the X
509 The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
510 a structure that describes a time interval in seconds and
513 typedef struct Tcl_Time {
518 The \fIusec\fR field should be less than 1000000.
521 Information provided to \fBTcl_SetMaxBlockTime\fR
522 is only used for the next call to \fBTcl_WaitForEvent\fR; it is
523 discarded after \fBTcl_WaitForEvent\fR returns.
525 The next time an event wait is done each of the event sources'
526 setup procedures will be called again, and they can specify new
527 information for that event wait.
530 If the application uses an external event loop rather than
531 \fBTcl_DoOneEvent\fR, the event sources may need to call
532 \fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
533 handler is registered that needs to poll for events, the event source
534 may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
535 force the external event loop to call Tcl. In this case,
536 \fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
537 interval seen since the last call to \fBTcl_DoOneEvent\fR or
538 \fBTcl_ServiceAll\fR.
540 In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
541 platform-specific procedures may also be available for
542 \fIsetupProc\fR, if there is additional information needed by
543 \fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
544 the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
547 The second procedure provided by each event source is its check
548 procedure, indicated by the \fIcheckProc\fR argument to
549 \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
552 typedef void Tcl_EventCheckProc(
553 ClientData \fIclientData\fR,
556 The arguments to this procedure are the same as those for \fIsetupProc\fR.
557 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
558 for events. Presumably at least one event source is now prepared to
559 queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
560 in turn, so they all have a chance to queue any events that are ready.
561 The check procedure does two things. First, it must see if any events
562 have triggered. Different event sources do this in different ways.
564 If an event source's check procedure detects an interesting event, it
565 must add the event to Tcl's event queue. To do this, the event source
566 calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
567 a dynamically allocated structure containing the event (see below for
568 more information on memory management issues). Each event source can
569 define its own event structure with whatever information is relevant
570 to that event source. However, the first element of the structure
571 must be a structure of type \fBTcl_Event\fR, and the address of this
572 structure is used when communicating between the event source and the
573 rest of the notifier. A \fBTcl_Event\fR has the following definition:
576 Tcl_EventProc *\fIproc\fR;
577 struct Tcl_Event *\fInextPtr\fR;
580 The event source must fill in the \fIproc\fR field of
581 the event before calling \fBTcl_QueueEvent\fR.
582 The \fInextPtr\fR is used to link together the events in the queue
583 and should not be modified by the event source.
585 An event may be added to the queue at any of three positions, depending
586 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
587 .IP \fBTCL_QUEUE_TAIL\fR 24
588 Add the event at the back of the queue, so that all other pending
589 events will be serviced first. This is almost always the right
590 place for new events.
591 .IP \fBTCL_QUEUE_HEAD\fR 24
592 Add the event at the front of the queue, so that it will be serviced
593 before all other queued events.
594 .IP \fBTCL_QUEUE_MARK\fR 24
595 Add the event at the front of the queue, unless there are other
596 events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
597 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
598 This value of \fIposition\fR is used to insert an ordered sequence of
599 events at the front of the queue, such as a series of
600 Enter and Leave events synthesized during a grab or ungrab operation
604 When it is time to handle an event from the queue (steps 1 and 4
605 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
607 in the first queued \fBTcl_Event\fR structure.
608 \fIProc\fR must match the following prototype:
610 typedef int Tcl_EventProc(
611 Tcl_Event *\fIevPtr\fR,
614 The first argument to \fIproc\fR is a pointer to the event, which will
615 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
616 added the event to the queue.
617 The second argument to \fIproc\fR is the \fIflags\fR argument for the
619 current call to \fBTcl_ServiceEvent\fR; this is used by the event source
621 to return immediately if its events are not relevant.
623 It is up to \fIproc\fR to handle the event, typically by invoking
624 one or more Tcl commands or C-level callbacks.
625 Once the event source has finished handling the event it returns 1
626 to indicate that the event can be removed from the queue.
627 If for some reason the event source decides that the event cannot
628 be handled at this time, it may return 0 to indicate that the event
630 should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
632 will go on to the next event in the queue and attempt to service it.
633 There are several reasons why an event source might defer an event.
634 One possibility is that events of this type are excluded by the
635 \fIflags\fR argument.
636 For example, the file event source will always return 0 if the
637 \fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
638 Another example of deferring events happens in Tk if
639 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
643 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
644 event from the event queue and free its storage.
645 Note that the storage for an event must be allocated by
646 the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
647 before calling \fBTcl_QueueEvent\fR, but it
648 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
650 Threaded applications work in a
651 similar manner, except that there is a separate event queue for
652 each thread containing a Tcl interpreter.
653 Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
654 an event to the current thread's queue.
655 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
656 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
657 which uniquely identifies a thread in a Tcl application. To obtain the
658 Tcl_ThreadID for the current thread, use the \fBTcl_GetCurrentThread\fR
659 procedure. (A thread would then need to pass this identifier to other
660 threads for those threads to be able to add events to its queue.)
661 After adding an event to another thread's queue, you then typically
662 need to call \fBTcl_ThreadAlert\fR to "wake up" that thread's notifier to
663 alert it to the new event.
665 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
666 events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
667 for each event in the queue, deleting those for with the procedure
668 returns 1. Events for which the procedure returns 0 are left in the
669 queue. \fIProc\fR should match the following prototype:
671 typedef int Tcl_EventDeleteProc(
672 Tcl_Event *\fIevPtr\fR,
673 ClientData \fIclientData\fR);
675 The \fIclientData\fR argument will be the same as the \fIclientData\fR
676 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
677 private information managed by the event source. The \fIevPtr\fR will
678 point to the next event in the queue.
680 \fBTcl_DeleteEventSource\fR deletes an event source. The \fIsetupProc\fR,
681 \fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
682 provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
683 If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
686 .SH "CREATING A NEW NOTIFIER"
688 The notifier consists of all the procedures described in this manual
689 entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
691 available on all platforms, and \fBTcl_CreateFileHandler\fR and
692 \fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
693 procedures are generic, in that they are the same for all notifiers.
694 However, eight of the procedures are notifier-dependent:
695 \fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR, \fBTcl_FinalizeNotifier\fR,
696 \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
697 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
698 support a new platform or to integrate Tcl with an
699 application-specific event loop, you must write new versions of these
702 \fBTcl_InitNotifier\fR initializes the notifier state and returns
703 a handle to the notifier state. Tcl calls this
704 procedure when initializing a Tcl interpreter. Similarly,
705 \fBTcl_FinalizeNotifier\fR shuts down the notifier, and is
706 called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
708 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
709 it is responsible for waiting for an ``interesting'' event to occur or
710 for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
711 each of the event sources' setup procedure will have been invoked.
712 The \fItimePtr\fR argument to
713 \fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
714 based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
715 and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
718 Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
719 to occur; it should not actually process the event in any way.
721 event sources will process the raw events and create Tcl_Events on
722 the event queue in their \fIcheckProc\fR procedures.
723 However, on some platforms (such as Windows) this isn't possible;
724 events may be processed in \fBTcl_WaitForEvent\fR, including queuing
725 Tcl_Events and more (for example, callbacks for native widgets may be
726 invoked). The return value from \fBTcl_WaitForEvent\fR must be either
727 0, 1, or \-1. On platforms such as Windows where events get processed in
728 \fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
729 events still pending that haven't been processed. This is a sign to the
730 caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
731 pending events to be processed. A 0 return value means that calling
732 \fBTcl_WaitForEvent\fR again will not have any effect: either this is a
733 platform where \fBTcl_WaitForEvent\fR only waits without doing any event
734 processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
735 additional events to process (e.g. it returned because the time
736 elapsed). Finally, a return value of \-1 means that the event loop is
737 no longer operational and the application should probably unwind and
738 terminate. Under Windows this happens when a WM_QUIT message is received;
739 under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
740 forever because there were no active event sources and the timeout was
743 \fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
744 any thread to "wake up" the notifier to alert it to new events on its
745 queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier
746 handle returned by \fBTcl_InitNotifier\fR.
748 If the notifier will be used with an external event loop, then it must
749 also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
750 invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
751 time has been reduced. \fBTcl_SetTimer\fR should arrange for the
752 external event loop to invoke \fBTcl_ServiceAll\fR after the specified
753 interval even if no events have occurred. This interface is needed
754 because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
756 notifier will only be used from \fBTcl_DoOneEvent\fR, then
757 \fBTcl_SetTimer\fR need not do anything.
759 On Unix systems, the file event source also needs support from the
760 notifier. The file event source consists of the
761 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
762 procedures, which are described in the \fBTcl_CreateFileHandler\fR
765 The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
766 in their respective manual pages.
768 The easiest way to create a new notifier is to look at the code
769 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
770 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
772 .SH "EXTERNAL EVENT LOOPS"
774 The notifier interfaces are designed so that Tcl can be embedded into
775 applications that have their own private event loops. In this case,
776 the application does not call \fBTcl_DoOneEvent\fR except in the case
777 of recursive event loops such as calls to the Tcl commands \fBupdate\fR
778 or \fBvwait\fR. Most of the time is spent in the external event loop
779 of the application. In this case the notifier must arrange for the
780 external event loop to call back into Tcl when something
781 happens on the various Tcl event sources. These callbacks should
782 arrange for appropriate Tcl events to be placed on the Tcl event queue.
784 Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
785 a regular basis, it is up to the notifier to arrange for
786 \fBTcl_ServiceEvent\fR to be called whenever events are pending on the
787 Tcl event queue. The easiest way to do this is to invoke
788 \fBTcl_ServiceAll\fR at the end of each callback from the external
789 event loop. This will ensure that all of the event sources are
790 polled, any queued events are serviced, and any pending idle handlers
791 are processed before returning control to the application. In
792 addition, event sources that need to poll for events can call
793 \fBTcl_SetMaxBlockTime\fR to force the external event loop to call
794 Tcl even if no events are available on the system event queue.
796 As a side effect of processing events detected in the main external
797 event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
798 loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
799 the external event loop, which will result in callbacks as described
800 in the preceding paragraph, which will result in calls to
801 \fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
802 service events in \fBTcl_ServiceAll\fR. Servicing events there is
803 unnecessary because control will immediately return to the
804 external event loop and hence to \fBTcl_DoOneEvent\fR, which can
805 service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
806 supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
807 normally services all pending events. To handle this situation,
808 \fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
809 that causes it to return without servicing any events.
810 This flag is called the \fIservice mode\fR;
811 \fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
813 In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
815 even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
816 when there is yet another recursive event loop invoked via an
817 event handler called by \fBTcl_DoOneEvent\fR (such as one that is
818 part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
819 have a chance to service events so \fBTcl_ServiceAll\fR must service
820 them all. Any recursive event loop that calls an external event
821 loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
822 that all events get processed in \fBTcl_ServiceAll\fR. This is done
823 by invoking the \fBTcl_SetServiceMode\fR procedure. If
824 \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
825 to \fBTcl_ServiceAll\fR will return immediately without processing any
826 events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
827 then calls to \fBTcl_ServiceAll\fR will behave normally.
828 \fBTcl_SetServiceMode\fR returns the previous value of the service
829 mode, which should be restored when the recursive loop exits.
830 \fBTcl_GetServiceMode\fR returns the current value of the service
834 \fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
835 \fBTcl_DoOneEvent\fR, \fBThread(3)\fR
837 event, notifier, event queue, event sources, file events, timer, idle, service mode, threads
OSDN Git Service
