| 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 |