Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1998-1999 Scriptics Corporation | |
3 | '\" Copyright (c) 1995-1997 Sun Microsystems, Inc. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: Notifier.3,v 1.9.2.1 2004/11/25 15:28:37 vasiljevic Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
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) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
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. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
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. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
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. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
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. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
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 | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
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 | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH Notifier 3 8.1 Tcl "Tcl Library Procedures" | |
247 | .BS | |
248 | .SH NAME | |
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 | |
250 | .SH SYNOPSIS | |
251 | .nf | |
252 | \fB#include <tcl.h>\fR | |
253 | .sp | |
254 | void | |
255 | \fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fR) | |
256 | .sp | |
257 | void | |
258 | \fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fR) | |
259 | .sp | |
260 | void | |
261 | \fBTcl_SetMaxBlockTime\fR(\fItimePtr\fR) | |
262 | .sp | |
263 | void | |
264 | \fBTcl_QueueEvent\fR(\fIevPtr, position\fR) | |
265 | .VS 8.1 | |
266 | .sp | |
267 | void | |
268 | \fBTcl_ThreadQueueEvent\fR(\fIthreadId, evPtr, position\fR) | |
269 | .sp | |
270 | void | |
271 | \fBTcl_ThreadAlert\fR(\fIthreadId\fR) | |
272 | .sp | |
273 | Tcl_ThreadId | |
274 | \fBTcl_GetCurrentThread\fR() | |
275 | .sp | |
276 | void | |
277 | \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR) | |
278 | .sp | |
279 | ClientData | |
280 | \fBTcl_InitNotifier\fR() | |
281 | .sp | |
282 | void | |
283 | \fBTcl_FinalizeNotifier\fR(\fIclientData\fR) | |
284 | .sp | |
285 | int | |
286 | \fBTcl_WaitForEvent\fR(\fItimePtr\fR) | |
287 | .sp | |
288 | void | |
289 | \fBTcl_AlertNotifier\fR(\fIclientData\fR) | |
290 | .sp | |
291 | void | |
292 | \fBTcl_SetTimer\fR(\fItimePtr\fR) | |
293 | .sp | |
294 | int | |
295 | \fBTcl_ServiceAll\fR() | |
296 | .sp | |
297 | int | |
298 | \fBTcl_ServiceEvent\fR(\fIflags\fR) | |
299 | .sp | |
300 | int | |
301 | \fBTcl_GetServiceMode\fR() | |
302 | .sp | |
303 | int | |
304 | \fBTcl_SetServiceMode\fR(\fImode\fR) | |
305 | .VE | |
306 | ||
307 | .SH ARGUMENTS | |
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, | |
314 | queues them. | |
315 | .AP ClientData clientData in | |
316 | Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or | |
317 | \fIdeleteProc\fR. | |
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 | |
323 | necessary. | |
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. | |
334 | .AP int flags in | |
335 | What types of events to service. These flags are the same as those | |
336 | passed to \fBTcl_DoOneEvent\fR. | |
337 | .VS 8.1 | |
338 | .AP int mode in | |
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. | |
341 | .VE | |
342 | .BE | |
343 | ||
344 | .SH INTRODUCTION | |
345 | .PP | |
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. | |
351 | .PP | |
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: | |
355 | .IP [1] | |
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. | |
367 | .IP [2] | |
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. | |
376 | .VS 8.1 | |
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. | |
386 | .IP [3] | |
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. | |
392 | .PP | |
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 | |
407 | Motif's. | |
408 | .SH "NOTIFIER BASICS" | |
409 | .VE | |
410 | .PP | |
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 | |
416 | things: | |
417 | .IP [1] | |
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 | .VS 8.1 | |
421 | from the queue, and return. It does this by calling | |
422 | \fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument. | |
423 | .VE | |
424 | .IP [2] | |
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 | |
428 | .VS 8.1 | |
429 | possibly call \fBTcl_SetMaxBlockTime\fR to limit how long | |
430 | .VE | |
431 | \fBTcl_WaitForEvent\fR will block if no new events occur. | |
432 | .IP [3] | |
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. | |
443 | .IP [4] | |
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. | |
447 | .IP [5] | |
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. | |
451 | .IP [6] | |
452 | See if there are idle callbacks pending. If so, invoke all of them and | |
453 | return. | |
454 | .IP [7] | |
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. | |
457 | ||
458 | .SH "CREATING A NEW EVENT SOURCE" | |
459 | .PP | |
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. | |
466 | .PP | |
467 | The procedure \fBTcl_CreateEventSource\fR creates a new event source. | |
468 | Its arguments specify the setup procedure and check procedure for | |
469 | the event source. | |
470 | \fISetupProc\fR should match the following prototype: | |
471 | .CS | |
472 | typedef void Tcl_EventSetupProc( | |
473 | ClientData \fIclientData\fR, | |
474 | int \fIflags\fR); | |
475 | .CE | |
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 | |
486 | bit. | |
487 | .PP | |
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. | |
496 | .VS 8.1 | |
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 | |
507 | connection. | |
508 | .VE | |
509 | The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to | |
510 | a structure that describes a time interval in seconds and | |
511 | microseconds: | |
512 | .CS | |
513 | typedef struct Tcl_Time { | |
514 | long \fIsec\fR; | |
515 | long \fIusec\fR; | |
516 | } Tcl_Time; | |
517 | .CE | |
518 | The \fIusec\fR field should be less than 1000000. | |
519 | .PP | |
520 | .VS 8.1 | |
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. | |
524 | .VE | |
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. | |
528 | .PP | |
529 | .VS 8.1 | |
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. | |
539 | .PP | |
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. | |
545 | .VE | |
546 | .PP | |
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 | |
550 | following prototype: | |
551 | .CS | |
552 | typedef void Tcl_EventCheckProc( | |
553 | ClientData \fIclientData\fR, | |
554 | int \fIflags\fR); | |
555 | .CE | |
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. | |
563 | .PP | |
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: | |
574 | .CS | |
575 | typedef struct { | |
576 | Tcl_EventProc *\fIproc\fR; | |
577 | struct Tcl_Event *\fInextPtr\fR; | |
578 | } Tcl_Event; | |
579 | .CE | |
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. | |
584 | .PP | |
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 | |
601 | in Tk. | |
602 | .PP | |
603 | .VS 8.1 | |
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 | |
606 | .VE | |
607 | in the first queued \fBTcl_Event\fR structure. | |
608 | \fIProc\fR must match the following prototype: | |
609 | .CS | |
610 | typedef int Tcl_EventProc( | |
611 | Tcl_Event *\fIevPtr\fR, | |
612 | int \fIflags\fR); | |
613 | .CE | |
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 | |
618 | .VS 8.1 | |
619 | current call to \fBTcl_ServiceEvent\fR; this is used by the event source | |
620 | .VE | |
621 | to return immediately if its events are not relevant. | |
622 | .PP | |
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 | |
629 | .VS 8.1 | |
630 | should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR | |
631 | .VE | |
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 | |
640 | of window events. | |
641 | .PP | |
642 | .VS 8.1 | |
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. | |
649 | .PP | |
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. | |
664 | .PP | |
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: | |
670 | .CS | |
671 | typedef int Tcl_EventDeleteProc( | |
672 | Tcl_Event *\fIevPtr\fR, | |
673 | ClientData \fIclientData\fR); | |
674 | .CE | |
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. | |
679 | .PP | |
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. | |
684 | .VE | |
685 | ||
686 | .SH "CREATING A NEW NOTIFIER" | |
687 | .PP | |
688 | The notifier consists of all the procedures described in this manual | |
689 | entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are | |
690 | .VS 8.1 | |
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 | |
700 | procedures. | |
701 | .PP | |
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. | |
707 | .PP | |
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 | |
716 | \fIflags\fR). | |
717 | .PP | |
718 | Ideally, \fBTcl_WaitForEvent\fR should only wait for an event | |
719 | to occur; it should not actually process the event in any way. | |
720 | Later on, the | |
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 | |
741 | infinite. | |
742 | .PP | |
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. | |
747 | .PP | |
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 | |
755 | event loop. If the | |
756 | notifier will only be used from \fBTcl_DoOneEvent\fR, then | |
757 | \fBTcl_SetTimer\fR need not do anything. | |
758 | .PP | |
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 | |
763 | manual page. | |
764 | .PP | |
765 | The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described | |
766 | in their respective manual pages. | |
767 | .PP | |
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. | |
771 | ||
772 | .SH "EXTERNAL EVENT LOOPS" | |
773 | .PP | |
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. | |
783 | .PP | |
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. | |
795 | .PP | |
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. | |
812 | .PP | |
813 | In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR | |
814 | to service events | |
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 | |
831 | mode. | |
832 | .VE | |
833 | .SH "SEE ALSO" | |
834 | \fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR, | |
835 | \fBTcl_DoOneEvent\fR, \fBThread(3)\fR | |
836 | .SH KEYWORDS | |
837 | event, notifier, event queue, event sources, file events, timer, idle, service mode, threads |