fileevent(3)
NAME
Tk::fileevent - Execute a callback when a filehandle
becomes readable or writable
SYNOPSIS
$widget->fileevent(fileHandle,readable?,callback?) $widget->fileevent(fileHandle,writable?,callback?)
DESCRIPTION
This command is used to create file event handlers. A
file event handler is a binding between a filehandle and a
callback, such that the callback is evaluated whenever the
filehandle becomes readable or writable. File event han
dlers 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
"<>", "sysread" or "read" on a blocking filehandle when
there is no input data available, the process will block;
until the input data arrives, it will not be able to ser
vice other events, so it will appear to the user to
``freeze up''. With fileevent, the process can tell when
data is present and only invoke gets or read when they
won't block.
The fileHandle argument to fileevent refers to an open
filehandle, such as the return value from a previous open
or socket command. If the callback argument is specified,
then fileevent creates a new event handler: callback will
be evaluated whenever the filehandle becomes readable or
writable (depending on the argument to fileevent). In
this case fileevent returns an empty string. The readable
and writable event handlers for a file are independent,
and may be created and deleted separately. However, there
may be at most one readable and one writable handler for a
file at a given time in a given interpreter. If fileevent
is called when the specified handler already exists in the
invoking interpreter, the new callback replaces the old
one.
If the callback argument is not specified, fileevent
returns the current callback for fileHandle, or an empty
string if there is none. If the callback argument is
specified as an empty string then the event handler is
deleted, so that no callback will be invoked. A file
event handler is also deleted automatically whenever its
filehandle is closed or its interpreter is deleted.
A filehandle is considered to be readable if there is
unread data available on the underlying device. A file
handle 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 callback 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 callback reads no data, returns, and
is immediately invoked again.
A filehandle 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.
Event-driven I/O works best for filehandles that have been
placed into nonblocking mode. In blocking mode, a "print"
command may block if you give it more data than the under
lying file or device can accept, and a "<>", "sysread" or
"read" command will block if you attempt to read more data
than is ready; no events will be processed while the com
mands block. In nonblocking mode "print", "<>", "sysread"
and "read" never block. See the documentation for the
individual commands for information on how they handle
blocking and nonblocking filehandles.
The callback for a file event is executed in the context
of $widget with which fileevent was invoked. If an error
occurs while executing the callback then the Tk::Error
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.
BUGS
On windows platforms fileevent is limited in the types of
filehandles that behave correctly. Making filefhandles
non-blocking is only implemented on a subset of UNIX plat
forms (see Tk::IO).
CREDITS
fileevent is based on the addinput command created by Mark
Diekhans.
SEE ALSO
Tk::IO Tk::callbacks
KEYWORDS
- asynchronous I/O, blocking, filehandle, event handler,
nonblocking, readable, callback, writable.