summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/fileevent.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/fileevent.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/fileevent.pod112
1 files changed, 0 insertions, 112 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod b/Master/tlpkg/tlperl/lib/Tk/fileevent.pod
deleted file mode 100644
index 1a98cfd6b71..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/fileevent.pod
+++ /dev/null
@@ -1,112 +0,0 @@
-# Copyright (c) 1994 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::fileevent - Execute a callback when a filehandle becomes readable or writable
-
-=for category Binding Events and Callbacks
-
-=head1 SYNOPSIS
-
-I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<readable>?,I<callback>?)
-
-I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<writable>?,I<callback>?)
-
-=head1 DESCRIPTION
-
-This command is used to create I<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
-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 C<E<lt>E<gt>>, C<sysread> or C<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 service other events, so it will
-appear to the user to ``freeze up''. With B<fileevent>, the process can
-tell when data is present and only invoke B<gets> or B<read> when
-they won't block.
-
-The I<fileHandle> argument to B<fileevent> refers to an open filehandle,
-such as the return value from a previous B<open> or B<socket>
-command.
-If the I<callback> argument is specified, then B<fileevent>
-creates a new event handler: I<callback> will be evaluated
-whenever the filehandle becomes readable or writable (depending on the
-argument to B<fileevent>).
-In this case B<fileevent> returns an empty string.
-The B<readable> and B<writable> event handlers for a file
-are independent, and may be created and deleted separately.
-However, there may be at most one B<readable> and one B<writable>
-handler for a file at a given time in a given interpreter.
-If B<fileevent> is called when the specified handler already
-exists in the invoking interpreter, the new callback replaces the old one.
-
-If the I<callback> argument is not specified, B<fileevent>
-returns the current callback for I<fileHandle>, or an empty string
-if there is none.
-If the I<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 filehandle 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<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 I<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 C<print> command may block if you give it
-more data than the underlying file or device can accept, and a
-C<E<lt>E<gt>>, C<sysread> or C<read> 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 C<print>, C<E<lt>E<gt>>, C<sysread> and C<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 I<$widget>
-with which B<fileevent> was invoked.
-If an error occurs while executing the callback then the
-L<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.
-
-=head1 BUGS
-
-On windows platforms B<fileevent> is limited in the types of filehandles
-that behave correctly. Making filefhandles non-blocking is only implemented
-on a subset of UNIX platforms (see L<Tk::IO>).
-
-=head1 CREDITS
-
-B<fileevent> is based on the B<addinput> command created
-by Mark Diekhans.
-
-=head1 SEE ALSO
-
-L<Tk::IO|Tk::IO>
-L<Tk::callbacks|Tk::callbacks>
-
-=head1 KEYWORDS
-
-asynchronous I/O, blocking, filehandle, event handler, nonblocking, readable,
-callback, writable.
-
-=cut
-