96 lines
6.0 KiB
HTML
96 lines
6.0 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - fileevent manual page</TITLE></HEAD><BODY>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
fileevent - Execute a script when a channel becomes readable or writable
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>fileevent </B><I>channelId </I><B>readable </B>?<I>script</I>?<BR>
|
|
<B>fileevent </B><I>channelId </I><B>writable </B>?<I>script</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
This command is used to create <I>file event handlers</I>. A file event
|
|
handler is a binding between a channel and a script, such that the script
|
|
is evaluated whenever the channel becomes readable or writable. File event
|
|
handlers are most commonly used to allow data to be received from another
|
|
process on an event-driven basis, so that the receiver can continue to
|
|
interact with the user while waiting for the data to arrive. If an
|
|
application invokes <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> on a blocking channel when
|
|
there is no input data available, the process will block; until the input
|
|
data arrives, it will not be able to service other events, so it will
|
|
appear to the user to ``freeze up''. With <B>fileevent</B>, the process can
|
|
tell when data is present and only invoke <B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> when
|
|
they won't block.
|
|
<P>
|
|
The <I>channelId</I> argument to <B>fileevent</B> refers to an open channel,
|
|
such as the return value from a previous <B><A HREF="../TkCmd/open.htm">open</A></B> or <B><A HREF="../TkCmd/socket.htm">socket</A></B>
|
|
command.
|
|
If the <I>script</I> argument is specified, then <B>fileevent</B>
|
|
creates a new event handler: <I>script</I> will be evaluated
|
|
whenever the channel becomes readable or writable (depending on the
|
|
second argument to <B>fileevent</B>).
|
|
In this case <B>fileevent</B> returns an empty string.
|
|
The <B>readable</B> and <B>writable</B> event handlers for a file
|
|
are independent, and may be created and deleted separately.
|
|
However, there may be at most one <B>readable</B> and one <B>writable</B>
|
|
handler for a file at a given time in a given interpreter.
|
|
If <B>fileevent</B> is called when the specified handler already
|
|
exists in the invoking interpreter, the new script replaces the old one.
|
|
<P>
|
|
If the <I>script</I> argument is not specified, <B>fileevent</B>
|
|
returns the current script for <I>channelId</I>, or an empty string
|
|
if there is none.
|
|
If the <I>script</I> argument is specified as an empty string
|
|
then the event handler is deleted, so that no script will be invoked.
|
|
A file event handler is also deleted automatically whenever
|
|
its channel is closed or its interpreter is deleted.
|
|
<P>
|
|
A channel is considered to be readable if there is unread data
|
|
available on the underlying device.
|
|
A channel is also considered to be readable if there is unread
|
|
data in an input buffer, except in the special case where the
|
|
most recent attempt to read from the channel was a <B><A HREF="../TkCmd/gets.htm">gets</A></B>
|
|
call that could not find a complete line in the input buffer.
|
|
This feature allows a file to be read a line at a time in nonblocking mode
|
|
using events.
|
|
A channel is also considered to be readable if an end of file or
|
|
error condition is present on the underlying file or device.
|
|
It is important for <I>script</I> to check for these conditions
|
|
and handle them appropriately; for example, if there is no special
|
|
check for end of file, an infinite loop may occur where <I>script</I>
|
|
reads no data, returns, and is immediately invoked again.
|
|
<P>
|
|
A channel is considered to be writable if at least one byte of data
|
|
can be written to the underlying file or device without blocking,
|
|
or if an error condition is present on the underlying file or device.
|
|
<P>
|
|
Event-driven I/O works best for channels that have been
|
|
placed into nonblocking mode with the <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B> command.
|
|
In blocking mode, a <B><A HREF="../TkCmd/puts.htm">puts</A></B> command may block if you give it
|
|
more data than the underlying file or device can accept, and a
|
|
<B><A HREF="../TkCmd/gets.htm">gets</A></B> or <B><A HREF="../TkCmd/read.htm">read</A></B> command will block if you attempt to read
|
|
more data than is ready; no events will be processed while the
|
|
commands block.
|
|
In nonblocking mode <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, and <B><A HREF="../TkCmd/gets.htm">gets</A></B> never block.
|
|
See the documentation for the individual commands for information
|
|
on how they handle blocking and nonblocking channels.
|
|
<P>
|
|
The script for a file event is executed at global level (outside the
|
|
context of any Tcl procedure) in the interpreter in which the
|
|
<B>fileevent</B> command was invoked.
|
|
If an error occurs while executing the script then the
|
|
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B> mechanism is used to report the error.
|
|
In addition, the file event handler is deleted if it ever returns
|
|
an error; this is done in order to prevent infinite loops due to
|
|
buggy handlers.
|
|
|
|
<H3><A NAME="M5">CREDITS</A></H3>
|
|
<B>fileevent</B> is based on the <B>addinput</B> command created
|
|
by Mark Diekhans.
|
|
|
|
<H3><A NAME="M6">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/bgerror.htm">bgerror</A></B>, <B><A HREF="../TkCmd/fconfigure.htm">fconfigure</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>
|
|
<H3><A NAME="M7">KEYWORDS</A></H3>
|
|
<A href="../Keywords/A.htm#asynchronous I/O">asynchronous I/O</A>, <A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/E.htm#event handler">event handler</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/R.htm#readable">readable</A>, <A href="../Keywords/S.htm#script">script</A>, <A href="../Keywords/W.htm#writable.">writable.</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994 The Regents of the University of California.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|