tcl/doc/fileevent.n

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 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$
   9 '\"
  10 .so man.macros
  11 .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 fileevent \- Execute a script when a channel becomes readable or writable
  16 .SH SYNOPSIS
  17 \fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR?
  18 .sp
  19 \fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR?
  20 .BE
  21
  22 .SH DESCRIPTION
  23 .PP
  24 This command is used to create \fIfile event handlers\fR.  A file event
  25 handler is a binding between a channel and a script, such that the script
  26 is evaluated whenever the channel becomes readable or writable.  File event
  27 handlers are most commonly used to allow data to be received from another
  28 process on an event-driven basis, so that the receiver can continue to
  29 interact with the user while waiting for the data to arrive.  If an
  30 application invokes \fBgets\fR or \fBread\fR on a blocking channel when
  31 there is no input data available, the process will block; until the input
  32 data arrives, it will not be able to service other events, so it will
  33 appear to the user to ``freeze up''.  With \fBfileevent\fR, the process can
  34 tell when data is present and only invoke \fBgets\fR or \fBread\fR when
  35 they won't block.
  36 .PP
  37 .VS
  38 The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
  39 channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
  40 or \fBstderr\fR), the return value from an invocation of \fBopen\fR
  41 or \fBsocket\fR, or the result of a channel creation command provided
  42 by a Tcl extension.
  43 .VE
  44 .PP
  45 If the \fIscript\fR argument is specified, then \fBfileevent\fR
  46 creates a new event handler:  \fIscript\fR will be evaluated
  47 whenever the channel becomes readable or writable (depending on the
  48 second argument to \fBfileevent\fR).
  49 In this case \fBfileevent\fR returns an empty string.
  50 The \fBreadable\fR and \fBwritable\fR event handlers for a file
  51 are independent, and may be created and deleted separately.
  52 However, there may be at most one \fBreadable\fR and one \fBwritable\fR
  53 handler for a file at a given time in a given interpreter.
  54 If \fBfileevent\fR is called when the specified handler already
  55 exists in the invoking interpreter, the new script replaces the old one.
  56 .PP
  57 If the \fIscript\fR argument is not specified, \fBfileevent\fR
  58 returns the current script for \fIchannelId\fR, or an empty string
  59 if there is none.
  60 If the \fIscript\fR argument is specified as an empty string
  61 then the event handler is deleted, so that no script will be invoked.
  62 A file event handler is also deleted automatically whenever
  63 its channel is closed or its interpreter is deleted.
  64 .PP
  65 A channel is considered to be readable if there is unread data
  66 available on the underlying device.
  67 A channel is also considered to be readable if there is unread
  68 data in an input buffer, except in the special case where the
  69 most recent attempt to read from the channel was a \fBgets\fR
  70 call that could not find a complete line in the input buffer.
  71 This feature allows a file to be read a line at a time in nonblocking mode
  72 using events.
  73 A channel is also considered to be readable if an end of file or
  74 error condition is present on the underlying file or device.
  75 It is important for \fIscript\fR to check for these conditions
  76 and handle them appropriately;  for example, if there is no special
  77 check for end of file, an infinite loop may occur where \fIscript\fR
  78 reads no data, returns, and is immediately invoked again.
  79 .PP
  80 A channel is considered to be writable if at least one byte of data
  81 can be written to the underlying file or device without blocking,
  82 or if an error condition is present on the underlying file or device.
  83 .PP
  84 Event-driven I/O works best for channels that have been
  85 placed into nonblocking mode with the \fBfconfigure\fR command.
  86 In blocking mode, a \fBputs\fR command may block if you give it
  87 more data than the underlying file or device can accept, and a
  88 \fBgets\fR or \fBread\fR command will block if you attempt to read
  89 more data than is ready;  no events will be processed while the
  90 commands block.
  91 In nonblocking mode \fBputs\fR, \fBread\fR, and \fBgets\fR never block.
  92 See the documentation for the individual commands for information
  93 on how they handle blocking and nonblocking channels.
  94 .PP
  95 The script for a file event is executed at global level (outside the
  96 context of any Tcl procedure) in the interpreter in which the
  97 \fBfileevent\fR command was invoked.
  98 If an error occurs while executing the script then the
  99 \fBbgerror\fR mechanism is used to report the error.
 100 In addition, the file event handler is deleted if it ever returns
 101 an error;  this is done in order to prevent infinite loops due to
 102 buggy handlers.
 103
 104 .SH EXAMPLE
 105 .PP
 106 .CS
 107  proc GetData {chan} {
 108     if {![eof $chan]} {
 109         puts [gets $chan]
 110     }
 111  }
 112
 113  fileevent $chan readable [list GetData $chan]
 114
 115 .CE
 116 In this setup \fBGetData\fR will be called with the channel as an
 117 argument whenever $chan becomes readable.
 118
 119 .SH CREDITS
 120 .PP
 121 \fBfileevent\fR is based on the \fBaddinput\fR command created
 122 by Mark Diekhans.
 123
 124 .SH "SEE ALSO"
 125 bgerror(n), fconfigure(n), gets(n), puts(n), read(n), Tcl_StandardChannels(3)
 126
 127 .SH KEYWORDS
 128 asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
 129 script, writable.