Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::fileevent - Execute a callback when a filehandle becomes readable or writable | |
11 | ||
12 | =for category Binding Events and Callbacks | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<readable>?,I<callback>?) | |
17 | ||
18 | I<$widget>-E<gt>B<fileevent>(I<fileHandle>,B<writable>?,I<callback>?) | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | This command is used to create I<file event handlers>. A file event | |
23 | handler is a binding between a filehandle and a callback, such that the callback | |
24 | is evaluated whenever the filehandle becomes readable or writable. File event | |
25 | handlers are most commonly used to allow data to be received from another | |
26 | process on an event-driven basis, so that the receiver can continue to | |
27 | interact with the user while waiting for the data to arrive. If an | |
28 | application invokes C<E<lt>E<gt>>, C<sysread> or C<read> on a blocking filehandle when | |
29 | there is no input data available, the process will block; until the input | |
30 | data arrives, it will not be able to service other events, so it will | |
31 | appear to the user to ``freeze up''. With B<fileevent>, the process can | |
32 | tell when data is present and only invoke B<gets> or B<read> when | |
33 | they won't block. | |
34 | ||
35 | The I<fileHandle> argument to B<fileevent> refers to an open filehandle, | |
36 | such as the return value from a previous B<open> or B<socket> | |
37 | command. | |
38 | If the I<callback> argument is specified, then B<fileevent> | |
39 | creates a new event handler: I<callback> will be evaluated | |
40 | whenever the filehandle becomes readable or writable (depending on the | |
41 | argument to B<fileevent>). | |
42 | In this case B<fileevent> returns an empty string. | |
43 | The B<readable> and B<writable> event handlers for a file | |
44 | are independent, and may be created and deleted separately. | |
45 | However, there may be at most one B<readable> and one B<writable> | |
46 | handler for a file at a given time in a given interpreter. | |
47 | If B<fileevent> is called when the specified handler already | |
48 | exists in the invoking interpreter, the new callback replaces the old one. | |
49 | ||
50 | If the I<callback> argument is not specified, B<fileevent> | |
51 | returns the current callback for I<fileHandle>, or an empty string | |
52 | if there is none. | |
53 | If the I<callback> argument is specified as an empty string | |
54 | then the event handler is deleted, so that no callback will be invoked. | |
55 | A file event handler is also deleted automatically whenever | |
56 | its filehandle is closed or its interpreter is deleted. | |
57 | ||
58 | A filehandle is considered to be readable if there is unread data | |
59 | available on the underlying device. | |
60 | A filehandle is also considered to be readable if an end of file or | |
61 | error condition is present on the underlying file or device. | |
62 | It is important for I<callback> to check for these conditions | |
63 | and handle them appropriately; for example, if there is no special | |
64 | check for end of file, an infinite loop may occur where I<callback> | |
65 | reads no data, returns, and is immediately invoked again. | |
66 | ||
67 | A filehandle is considered to be writable if at least one byte of data | |
68 | can be written to the underlying file or device without blocking, | |
69 | or if an error condition is present on the underlying file or device. | |
70 | ||
71 | Event-driven I/O works best for filehandles that have been | |
72 | placed into nonblocking mode. | |
73 | In blocking mode, a C<print> command may block if you give it | |
74 | more data than the underlying file or device can accept, and a | |
75 | C<E<lt>E<gt>>, C<sysread> or C<read> command will block if you attempt to read | |
76 | more data than is ready; no events will be processed while the | |
77 | commands block. | |
78 | In nonblocking mode C<print>, C<E<lt>E<gt>>, C<sysread> and C<read> never block. | |
79 | See the documentation for the individual commands for information | |
80 | on how they handle blocking and nonblocking filehandles. | |
81 | ||
82 | The callback for a file event is executed in the context of I<$widget> | |
83 | with which B<fileevent> was invoked. | |
84 | If an error occurs while executing the callback then the | |
85 | L<Tk::Error> mechanism is used to report the error. | |
86 | In addition, the file event handler is deleted if it ever returns | |
87 | an error; this is done in order to prevent infinite loops due to | |
88 | buggy handlers. | |
89 | ||
90 | =head1 BUGS | |
91 | ||
92 | On windows platforms B<fileevent> is limited in the types of filehandles | |
93 | that behave correctly. Making filefhandles non-blocking is only implemented | |
94 | on a subset of UNIX platforms (see L<Tk::IO>). | |
95 | ||
96 | =head1 CREDITS | |
97 | ||
98 | B<fileevent> is based on the B<addinput> command created | |
99 | by Mark Diekhans. | |
100 | ||
101 | =head1 SEE ALSO | |
102 | ||
103 | L<Tk::IO|Tk::IO> | |
104 | L<Tk::callbacks|Tk::callbacks> | |
105 | ||
106 | =head1 KEYWORDS | |
107 | ||
108 | asynchronous I/O, blocking, filehandle, event handler, nonblocking, readable, | |
109 | callback, writable. | |
110 | ||
111 | =cut | |
112 |