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