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 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
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 manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
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.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .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
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 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
281 \fB#include <tcl.h>\fR
284 \fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
287 \fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR)
290 \fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR)
293 \fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
296 \fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR)
299 \fBTcl_ThreadAlert\fR(\fIthreadId\fR)
302 \fBTcl_GetCurrentThread\fR()
305 \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
308 \fBTcl_InitNotifier\fR()
311 \fBTcl_FinalizeNotifier\fR(\fIclientData\fR)
314 \fBTcl_WaitForEvent\fR(\fItimePtr\fR)
317 \fBTcl_AlertNotifier\fR(\fIclientData\fR)
320 \fBTcl_SetTimer\fR(\fItimePtr\fR)
323 \fBTcl_ServiceAll\fR()
326 \fBTcl_ServiceEvent\fR(\fIflags\fR)
329 \fBTcl_GetServiceMode\fR()
332 \fBTcl_SetServiceMode\fR(\fImode\fR)
335 \fBTcl_ServiceModeHook\fR(\fImode\fR)
338 \fBTcl_SetNotifier\fR(\fInotifierProcPtr\fR)
340 .AS Tcl_EventDeleteProc *notifierProcPtr
341 .AP Tcl_EventSetupProc *setupProc in
342 Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
343 .AP Tcl_EventCheckProc *checkProc in
344 Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
345 events. Checks to see if any events have occurred and, if so,
347 .AP ClientData clientData in
348 Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
350 .AP "const Tcl_Time" *timePtr in
351 Indicates the maximum amount of time to wait for an event. This
352 is specified as an interval (how long to wait), not an absolute
353 time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
354 is NULL, it means there is no maximum wait time: wait forever if
356 .AP Tcl_Event *evPtr in
357 An event to add to the event queue. The storage for the event must
358 have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
359 .AP Tcl_QueuePosition position in
360 Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
361 \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
362 .AP Tcl_ThreadId threadId in
363 A unique identifier for a thread.
364 .AP Tcl_EventDeleteProc *deleteProc in
365 Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
367 What types of events to service. These flags are the same as those
368 passed to \fBTcl_DoOneEvent\fR.
370 Indicates whether events should be serviced by \fBTcl_ServiceAll\fR.
371 Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
372 .AP Tcl_NotifierProcs* notifierProcPtr in
373 Structure of function pointers describing notifier procedures that are
374 to replace the ones installed in the executable. See
375 \fBREPLACING THE NOTIFIER\fR for details.
379 The interfaces described here are used to customize the Tcl event
380 loop. The two most common customizations are to add new sources of
381 events and to merge Tcl's event loop with some other event loop, such
382 as one provided by an application in which Tcl is embedded. Each of
383 these tasks is described in a separate section below.
385 The procedures in this manual entry are the building blocks out of which
386 the Tcl event notifier is constructed. The event notifier is the lowest
387 layer in the Tcl event mechanism. It consists of three things:
389 Event sources: these represent the ways in which events can be
390 generated. For example, there is a timer event source that implements
391 the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
392 command, and there is a file event source that implements the
393 \fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
394 source must work with the notifier to detect events at the right
395 times, record them on the event queue, and eventually notify
396 higher-level software that they have occurred. The procedures
397 \fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
398 and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
399 \fBTcl_DeleteEvents\fR are used primarily by event sources.
401 The event queue: for non-threaded applications,
402 there is a single queue for the whole application,
403 containing events that have been detected but not yet serviced. Event
404 sources place events onto the queue so that they may be processed in
405 order at appropriate times during the event loop. The event queue
406 guarantees a fair discipline of event handling, so that no event
407 source can starve the others. It also allows events to be saved for
408 servicing at a future time. Threaded applications work in a
409 similar manner, except that there is a separate event queue for
410 each thread containing a Tcl interpreter.
411 \fBTcl_QueueEvent\fR is used (primarily
412 by event sources) to add events to the event queue and
413 \fBTcl_DeleteEvents\fR is used to remove events from the queue without
414 processing them. In a threaded application, \fBTcl_QueueEvent\fR adds
415 an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
416 adds an event to a queue in a specific thread.
418 The event loop: in order to detect and process events, the application
419 enters a loop that waits for events to occur, places them on the event
420 queue, and then processes them. Most applications will do this by
421 calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
422 separate manual entry.
424 Most Tcl applications need not worry about any of the internals of
425 the Tcl notifier. However, the notifier now has enough flexibility
426 to be retargeted either for a new platform or to use an external event
427 loop (such as the Motif event loop, when Tcl is embedded in a Motif
428 application). The procedures \fBTcl_WaitForEvent\fR and
429 \fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
430 replaced with new versions to retarget the notifier (the
431 \fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
432 \fBTcl_FinalizeNotifier\fR, \fBTcl_Sleep\fR,
433 \fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
434 also be replaced; see CREATING A NEW NOTIFIER below for details).
435 The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
436 \fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
437 to help connect Tcl's event loop to an external event loop such as
439 .SH "NOTIFIER BASICS"
441 The easiest way to understand how the notifier works is to consider
442 what happens when \fBTcl_DoOneEvent\fR is called.
443 \fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
444 what sort of events it is OK to process and also whether or not to
445 block if no events are ready. \fBTcl_DoOneEvent\fR does the following
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. It does this by calling
451 \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
453 Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
454 invokes a \fIsetup procedure\fR in each event source.
455 The event source will perform event-source specific initialization and
456 possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
457 \fBTcl_WaitForEvent\fR will block if no new events occur.
459 Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
460 on different platforms; it waits for an event to occur, based on the
461 information provided by the event sources.
462 It may cause the application to block if \fItimePtr\fR specifies
463 an interval other than 0.
464 \fBTcl_WaitForEvent\fR returns when something has happened,
465 such as a file becoming readable or the interval given by \fItimePtr\fR
466 expiring. If there are no events for \fBTcl_WaitForEvent\fR to
467 wait for, so that it would block forever, then it returns immediately
468 and \fBTcl_DoOneEvent\fR returns 0.
470 Call a \fIcheck procedure\fR in each event source. The check
471 procedure determines whether any events of interest to this source
472 occurred. If so, the events are added to the event queue.
474 Check the event queue to see if it contains any events that can
475 be serviced. If so, service the first possible event, remove it
476 from the queue, and return.
478 See if there are idle callbacks pending. If so, invoke all of them and
481 Either return 0 to indicate that no events were ready, or go back to
482 step [2] if blocking was requested by the caller.
483 .SH "CREATING A NEW EVENT SOURCE"
485 An event source consists of three procedures invoked by the notifier,
486 plus additional C procedures that are invoked by higher-level code
487 to arrange for event-driven callbacks. The three procedures called
488 by the notifier consist of the setup and check procedures described
489 above, plus an additional procedure that is invoked when an event
490 is removed from the event queue for servicing.
492 The procedure \fBTcl_CreateEventSource\fR creates a new event source.
493 Its arguments specify the setup procedure and check procedure for
495 \fISetupProc\fR should match the following prototype:
498 typedef void \fBTcl_EventSetupProc\fR(
499 ClientData \fIclientData\fR,
503 The \fIclientData\fR argument will be the same as the \fIclientData\fR
504 argument to \fBTcl_CreateEventSource\fR; it is typically used to
505 point to private information managed by the event source.
506 The \fIflags\fR argument will be the same as the \fIflags\fR
507 argument passed to \fBTcl_DoOneEvent\fR except that it will never
508 be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
509 \fIFlags\fR indicates what kinds of events should be considered;
510 if the bit corresponding to this event source is not set, the event
511 source should return immediately without doing anything. For
512 example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
515 \fISetupProc\fR's job is to make sure that the application wakes up
516 when events of the desired type occur. This is typically done in a
517 platform-dependent fashion. For example, under Unix an event source
518 might call \fBTcl_CreateFileHandler\fR; under Windows it might
519 request notification with a Windows event. For timer-driven event
520 sources such as timer events or any polled event, the event source
521 can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
522 up after a specified time even if no events have occurred.
523 If no event source calls \fBTcl_SetMaxBlockTime\fR
524 then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
525 event to occur; otherwise, it will only wait as long as the shortest
526 interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
527 sources. If an event source knows that it already has events ready to
528 report, it can request a zero maximum block time. For example, the
529 setup procedure for the X event source looks to see if there are
530 events already queued. If there are, it calls
531 \fBTcl_SetMaxBlockTime\fR with a 0 block time so that
532 \fBTcl_WaitForEvent\fR does not block if there is no new data on the X
534 The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
535 a structure that describes a time interval in seconds and
539 typedef struct Tcl_Time {
545 The \fIusec\fR field should be less than 1000000.
547 Information provided to \fBTcl_SetMaxBlockTime\fR
548 is only used for the next call to \fBTcl_WaitForEvent\fR; it is
549 discarded after \fBTcl_WaitForEvent\fR returns.
550 The next time an event wait is done each of the event sources'
551 setup procedures will be called again, and they can specify new
552 information for that event wait.
554 If the application uses an external event loop rather than
555 \fBTcl_DoOneEvent\fR, the event sources may need to call
556 \fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
557 handler is registered that needs to poll for events, the event source
558 may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
559 force the external event loop to call Tcl. In this case,
560 \fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
561 interval seen since the last call to \fBTcl_DoOneEvent\fR or
562 \fBTcl_ServiceAll\fR.
564 In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
565 platform-specific procedures may also be available for
566 \fIsetupProc\fR, if there is additional information needed by
567 \fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
568 the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
570 The second procedure provided by each event source is its check
571 procedure, indicated by the \fIcheckProc\fR argument to
572 \fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
576 typedef void \fBTcl_EventCheckProc\fR(
577 ClientData \fIclientData\fR,
581 The arguments to this procedure are the same as those for \fIsetupProc\fR.
582 \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
583 for events. Presumably at least one event source is now prepared to
584 queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
585 in turn, so they all have a chance to queue any events that are ready.
586 The check procedure does two things. First, it must see if any events
587 have triggered. Different event sources do this in different ways.
589 If an event source's check procedure detects an interesting event, it
590 must add the event to Tcl's event queue. To do this, the event source
591 calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
592 a dynamically allocated structure containing the event (see below for
593 more information on memory management issues). Each event source can
594 define its own event structure with whatever information is relevant
595 to that event source. However, the first element of the structure
596 must be a structure of type \fBTcl_Event\fR, and the address of this
597 structure is used when communicating between the event source and the
598 rest of the notifier. A \fBTcl_Event\fR has the following definition:
602 Tcl_EventProc *\fIproc\fR;
603 struct Tcl_Event *\fInextPtr\fR;
607 The event source must fill in the \fIproc\fR field of
608 the event before calling \fBTcl_QueueEvent\fR.
609 The \fInextPtr\fR is used to link together the events in the queue
610 and should not be modified by the event source.
612 An event may be added to the queue at any of three positions, depending
613 on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
614 .IP \fBTCL_QUEUE_TAIL\fR 24
615 Add the event at the back of the queue, so that all other pending
616 events will be serviced first. This is almost always the right
617 place for new events.
618 .IP \fBTCL_QUEUE_HEAD\fR 24
619 Add the event at the front of the queue, so that it will be serviced
620 before all other queued events.
621 .IP \fBTCL_QUEUE_MARK\fR 24
622 Add the event at the front of the queue, unless there are other
623 events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
624 add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
625 This value of \fIposition\fR is used to insert an ordered sequence of
626 events at the front of the queue, such as a series of
627 Enter and Leave events synthesized during a grab or ungrab operation
630 When it is time to handle an event from the queue (steps 1 and 4
631 above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
632 in the first queued \fBTcl_Event\fR structure.
633 \fIProc\fR must match the following prototype:
636 typedef int \fBTcl_EventProc\fR(
637 Tcl_Event *\fIevPtr\fR,
641 The first argument to \fIproc\fR is a pointer to the event, which will
642 be the same as the first argument to the \fBTcl_QueueEvent\fR call that
643 added the event to the queue.
644 The second argument to \fIproc\fR is the \fIflags\fR argument for the
645 current call to \fBTcl_ServiceEvent\fR; this is used by the event source
646 to return immediately if its events are not relevant.
648 It is up to \fIproc\fR to handle the event, typically by invoking
649 one or more Tcl commands or C-level callbacks.
650 Once the event source has finished handling the event it returns 1
651 to indicate that the event can be removed from the queue.
652 If for some reason the event source decides that the event cannot
653 be handled at this time, it may return 0 to indicate that the event
654 should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
655 will go on to the next event in the queue and attempt to service it.
656 There are several reasons why an event source might defer an event.
657 One possibility is that events of this type are excluded by the
658 \fIflags\fR argument.
659 For example, the file event source will always return 0 if the
660 \fBTCL_FILE_EVENTS\fR bit is not set in \fIflags\fR.
661 Another example of deferring events happens in Tk if
662 \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
665 When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
666 event from the event queue and free its storage.
667 Note that the storage for an event must be allocated by
668 the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
669 before calling \fBTcl_QueueEvent\fR, but it
670 will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
672 Threaded applications work in a
673 similar manner, except that there is a separate event queue for
674 each thread containing a Tcl interpreter.
675 Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
676 an event to the current thread's queue.
677 To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
678 \fBTcl_ThreadQueueEvent\fR accepts as an argument a Tcl_ThreadId argument,
679 which uniquely identifies a thread in a Tcl application. To obtain the
680 Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR
681 procedure. (A thread would then need to pass this identifier to other
682 threads for those threads to be able to add events to its queue.)
683 After adding an event to another thread's queue, you then typically
684 need to call \fBTcl_ThreadAlert\fR to
686 that thread's notifier to alert it to the new event.
688 \fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
689 events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
690 for each event in the queue, deleting those for with the procedure
691 returns 1. Events for which the procedure returns 0 are left in the
692 queue. \fIProc\fR should match the following prototype:
695 typedef int \fBTcl_EventDeleteProc\fR(
696 Tcl_Event *\fIevPtr\fR,
697 ClientData \fIclientData\fR);
700 The \fIclientData\fR argument will be the same as the \fIclientData\fR
701 argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
702 private information managed by the event source. The \fIevPtr\fR will
703 point to the next event in the queue.
705 \fBTcl_DeleteEventSource\fR deletes an event source. The \fIsetupProc\fR,
706 \fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
707 provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
708 If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
709 .SH "CREATING A NEW NOTIFIER"
711 The notifier consists of all the procedures described in this manual
712 entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
713 available on all platforms, and \fBTcl_CreateFileHandler\fR and
714 \fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
715 procedures are generic, in that they are the same for all notifiers.
716 However, none of the procedures are notifier-dependent:
717 \fBTcl_InitNotifier\fR, \fBTcl_AlertNotifier\fR,
718 \fBTcl_FinalizeNotifier\fR, \fBTcl_SetTimer\fR, \fBTcl_Sleep\fR,
719 \fBTcl_WaitForEvent\fR, \fBTcl_CreateFileHandler\fR,
720 \fBTcl_DeleteFileHandler\fR and \fBTcl_ServiceModeHook\fR. To support a
721 new platform or to integrate Tcl with an application-specific event loop,
722 you must write new versions of these procedures.
724 \fBTcl_InitNotifier\fR initializes the notifier state and returns
725 a handle to the notifier state. Tcl calls this
726 procedure when initializing a Tcl interpreter. Similarly,
727 \fBTcl_FinalizeNotifier\fR shuts down the notifier, and is
728 called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
730 \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
731 it is responsible for waiting for an
734 for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
735 each of the event sources' setup procedure will have been invoked.
736 The \fItimePtr\fR argument to
737 \fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
738 based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
739 and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
742 Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
743 to occur; it should not actually process the event in any way.
745 event sources will process the raw events and create Tcl_Events on
746 the event queue in their \fIcheckProc\fR procedures.
747 However, on some platforms (such as Windows) this is not possible;
748 events may be processed in \fBTcl_WaitForEvent\fR, including queuing
749 Tcl_Events and more (for example, callbacks for native widgets may be
750 invoked). The return value from \fBTcl_WaitForEvent\fR must be either
751 0, 1, or \-1. On platforms such as Windows where events get processed in
752 \fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
753 events still pending that have not been processed. This is a sign to the
754 caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
755 pending events to be processed. A 0 return value means that calling
756 \fBTcl_WaitForEvent\fR again will not have any effect: either this is a
757 platform where \fBTcl_WaitForEvent\fR only waits without doing any event
758 processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
759 additional events to process (e.g. it returned because the time
760 elapsed). Finally, a return value of \-1 means that the event loop is
761 no longer operational and the application should probably unwind and
762 terminate. Under Windows this happens when a WM_QUIT message is received;
763 under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
764 forever because there were no active event sources and the timeout was
767 \fBTcl_AlertNotifier\fR is used in multithreaded applications to allow
770 the notifier to alert it to new events on its
771 queue. \fBTcl_AlertNotifier\fR requires as an argument the notifier
772 handle returned by \fBTcl_InitNotifier\fR.
774 If the notifier will be used with an external event loop, then it must
775 also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
776 invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
777 time has been reduced. \fBTcl_SetTimer\fR should arrange for the
778 external event loop to invoke \fBTcl_ServiceAll\fR after the specified
779 interval even if no events have occurred. This interface is needed
780 because \fBTcl_WaitForEvent\fR is not invoked when there is an external
782 notifier will only be used from \fBTcl_DoOneEvent\fR, then
783 \fBTcl_SetTimer\fR need not do anything.
785 \fBTcl_ServiceModeHook\fR is called by the platform-independent portion
786 of the notifier when client code makes a call to
787 \fBTcl_SetServiceMode\fR. This hook is provided to support operating
788 systems that require special event handling when the application is in
789 a modal loop (the Windows notifier, for instance, uses this hook to
790 create a communication window).
792 On Unix systems, the file event source also needs support from the
793 notifier. The file event source consists of the
794 \fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
795 procedures, which are described in the \fBTcl_CreateFileHandler\fR
798 The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
799 in their respective manual pages.
801 The easiest way to create a new notifier is to look at the code
802 for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
803 or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
804 .SH "REPLACING THE NOTIFIER"
806 A notifier that has been written according to the conventions above
807 can also be installed in a running process in place of the standard
808 notifier. This mechanism is used so that a single executable can be
809 used (with the standard notifier) as a stand-alone program and reused
810 (with a replacement notifier in a loadable extension) as an extension
811 to another program, such as a Web browser plugin.
813 To do this, the extension makes a call to \fBTcl_SetNotifier\fR
814 passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The
815 structure has the following layout:
818 typedef struct Tcl_NotifierProcs {
819 Tcl_SetTimerProc *\fIsetTimerProc\fR;
820 Tcl_WaitForEventProc *\fIwaitForEventProc\fR;
821 Tcl_CreateFileHandlerProc *\fIcreateFileHandlerProc\fR;
822 Tcl_DeleteFileHandlerProc *\fIdeleteFileHandlerProc\fR;
823 Tcl_InitNotifierProc *\fIinitNotifierProc\fR;
824 Tcl_FinalizeNotifierProc *\fIfinalizeNotifierProc\fR;
825 Tcl_AlertNotifierProc *\fIalertNotifierProc\fR;
826 Tcl_ServiceModeHookProc *\fIserviceModeHookProc\fR;
827 } \fBTcl_NotifierProcs\fR;
830 Following the call to \fBTcl_SetNotifier\fR, the pointers given in
831 the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
832 been installed in the process.
834 It is extraordinarily unwise to replace a running notifier. Normally,
835 \fBTcl_SetNotifier\fR should be called at process initialization time
836 before the first call to \fBTcl_InitNotifier\fR.
837 .SH "EXTERNAL EVENT LOOPS"
839 The notifier interfaces are designed so that Tcl can be embedded into
840 applications that have their own private event loops. In this case,
841 the application does not call \fBTcl_DoOneEvent\fR except in the case
842 of recursive event loops such as calls to the Tcl commands \fBupdate\fR
843 or \fBvwait\fR. Most of the time is spent in the external event loop
844 of the application. In this case the notifier must arrange for the
845 external event loop to call back into Tcl when something
846 happens on the various Tcl event sources. These callbacks should
847 arrange for appropriate Tcl events to be placed on the Tcl event queue.
849 Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
850 a regular basis, it is up to the notifier to arrange for
851 \fBTcl_ServiceEvent\fR to be called whenever events are pending on the
852 Tcl event queue. The easiest way to do this is to invoke
853 \fBTcl_ServiceAll\fR at the end of each callback from the external
854 event loop. This will ensure that all of the event sources are
855 polled, any queued events are serviced, and any pending idle handlers
856 are processed before returning control to the application. In
857 addition, event sources that need to poll for events can call
858 \fBTcl_SetMaxBlockTime\fR to force the external event loop to call
859 Tcl even if no events are available on the system event queue.
861 As a side effect of processing events detected in the main external
862 event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
863 loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
864 the external event loop, which will result in callbacks as described
865 in the preceding paragraph, which will result in calls to
866 \fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
867 service events in \fBTcl_ServiceAll\fR. Servicing events there is
868 unnecessary because control will immediately return to the
869 external event loop and hence to \fBTcl_DoOneEvent\fR, which can
870 service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
871 supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
872 normally services all pending events. To handle this situation,
873 \fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
874 that causes it to return without servicing any events.
875 This flag is called the \fIservice mode\fR;
876 \fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
878 In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
880 even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
881 when there is yet another recursive event loop invoked via an
882 event handler called by \fBTcl_DoOneEvent\fR (such as one that is
883 part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
884 have a chance to service events so \fBTcl_ServiceAll\fR must service
885 them all. Any recursive event loop that calls an external event
886 loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
887 that all events get processed in \fBTcl_ServiceAll\fR. This is done
888 by invoking the \fBTcl_SetServiceMode\fR procedure. If
889 \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
890 to \fBTcl_ServiceAll\fR will return immediately without processing any
891 events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
892 then calls to \fBTcl_ServiceAll\fR will behave normally.
893 \fBTcl_SetServiceMode\fR returns the previous value of the service
894 mode, which should be restored when the recursive loop exits.
895 \fBTcl_GetServiceMode\fR returns the current value of the service
898 Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3),
899 Tcl_DoOneEvent(3), Thread(3)
901 event, notifier, event queue, event sources, file events, timer, idle, service mode, threads
OSDN Git Service
