1=head1 NAME 2 3Prima::File - asynchronous stream I/O. 4 5=head1 SYNOPSIS 6 7 use strict; 8 use Prima qw(Application); 9 10 # create pipe and autoflush the writer end 11 pipe(READ, WRITE) or die "pipe():$!\n"; 12 select WRITE; 13 $|=1; 14 select STDOUT; 15 16 # create Prima listener on the reader end 17 my $read = Prima::File-> new( 18 file => \*READ, 19 mask => fe::Read, 20 onRead => sub { 21 $_ = <READ>; 22 print "read:$_\n"; 23 }, 24 ); 25 26 print WRITE "line\n"; 27 run Prima; 28 29=head1 DESCRIPTION 30 31Prima::File provides access to the I/O stream events, 32that are called when a file handle becomes readable, writable 33or if an exception occurred. Registering file handles to Prima::File 34objects makes possible the stream operations coexist with the event loop. 35 36=head1 USAGE 37 38Prima::File is a descendant of Prima::Component. 39Objects of Prima::File class must be binded to a valid file handle object, 40before the associated events can occur: 41 42 my $f = Prima::File-> create(); 43 $f-> file( *STDIN); 44 45When a file handle, binded via the C<::file> property becomes readable, 46writable or when an exception signaled, one of three correspondent 47events called - C<Read>, C<Write> or C<Exception>. When a handle is 48always readable, or always writable, or, some of these events are 49desired to be blocked, the file event mask can be set via the C<::mask> 50property: 51 52 $f-> mask( fe::Read | fe::Exception); 53 54NB. Due to different system implementations, the only handles, 55currently supported on all systems, are socket handle and disk file 56handles. Pipes only work on unix platforms. The example file I<socket.pl> 57elucidates the use of sockets together with Prima::File. 58 59When a file handle is not needed anymore, it is expected to 60be detached from an object explicitly: 61 62 $f-> file( undef); 63 64However, if the system detects that a file handle is no longer valid, 65it is automatically detached. It is possible to check, if a file handle 66is still valid by calling the C<is_active()> method. 67 68Prima::File events are basically the same I/O callbacks, provided by 69a system C<select()> call. See documentation of your system's select() 70for the implementation details. 71 72=head1 API 73 74=head2 Properties 75 76=over 77 78=item file HANDLE 79 80Selects a file handle, that is to be monitored for stream I/O events. 81If HANDLE is C<undef>, object is returned to a passive state, and 82the previously binded file handle is de-selected. 83 84=item fd INTEGER 85 86Same as file(), but to be used for file descriptiors. When this property is used, 87consequent get-calls to file() will return undef. 88 89=item mask EVENT_MASK 90 91Selects a event mask, that is a combination of C<fe::XXX> integer constants, 92each representing an event: 93 94 fe::Read 95 fe::Write 96 fe::Exception 97 98The omitted events are effectively excluded from the system file event 99multiplexing mechanism. 100 101=back 102 103=head2 Methods 104 105=over 106 107=item get_handle 108 109Returns C<sprintf("0x%08x", fileno( file ))> string. 110If C<::file> is C<undef>, -1 is used instead fileno() result. 111 112=item is_active AUTODETACH = 0 113 114Returns a boolean flag, indicating if a file handle is valid. 115If AUTODETACH is 1, and the file handle is not valid, 116C<file(undef)> is called. 117 118=back 119 120=head2 Events 121 122=over 123 124=item Read 125 126Called when a file handle becomes readable. The callback procedure 127is expected to call a non-blocking read() on the file handle. 128 129=item Write 130 131Called when a file handle becomes writable. The callback procedure 132is expected to call a non-blocking write() on the file handle. 133 134=item Exception 135 136Called when an exception is signaled on a file handle. 137The exceptions are specific to handle type and the operating system. 138For example, a unix socket signals C<Exception> when a control status 139data for a pseudo terminal or an out-of-band data arrives. 140 141=back 142 143=head1 AUTHOR 144 145Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>. 146 147=head1 SEE ALSO 148 149L<Prima>, L<Prima::Object> 150 151