.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "pod::Prima::File 3"
.TH pod::Prima::File 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::File \- asynchronous stream I/O.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use strict;
\&  use Prima qw(Application);
\&
\&  # create pipe and autoflush the writer end
\&  pipe(READ, WRITE) or die "pipe():$!\en"; 
\&  select WRITE;
\&  $|=1;
\&  select STDOUT;
\&
\&  # create Prima listener on the reader end
\&  my $read = Prima::File\-> new(
\&      file => \e*READ,
\&      mask => fe::Read,
\&      onRead => sub {
\&         $_ = <READ>;
\&         print "read:$_\en";
\&      },
\&  );
\&
\&  print WRITE "line\en";
\&  run Prima;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Prima::File provides access to the I/O stream events,
that are called when a file handle becomes readable, writable
or if an exception occurred. Registering file handles to Prima::File
objects makes possible the stream operations coexist with the event loop.
.SH "USAGE"
.IX Header "USAGE"
Prima::File is a descendant of Prima::Component.
Objects of Prima::File class must be binded to a valid file handle object,
before the associated events can occur:
.PP
.Vb 2
\&  my $f = Prima::File\-> create();
\&  $f\-> file( *STDIN);
.Ve
.PP
When a file handle, binded via the \f(CW\*(C`::file\*(C'\fR property becomes readable,
writable or when an exception signaled, one of three correspondent
events called \- \f(CW\*(C`Read\*(C'\fR, \f(CW\*(C`Write\*(C'\fR or \f(CW\*(C`Exception\*(C'\fR. When a handle is
always readable, or always writable, or, some of these events are
desired to be blocked, the file event mask can be set via the \f(CW\*(C`::mask\*(C'\fR
property:
.PP
.Vb 1
\&  $f\-> mask( fe::Read | fe::Exception);
.Ve
.PP
\&\s-1NB\s0. Due to different system implementations, the only handles,
currently supported on all systems, are socket handle and disk file 
handles. Pipes only work on unix platforms. The example file \fIsocket.pl\fR
elucidates the use of sockets together with Prima::File.
.PP
When a file handle is not needed anymore, it is expected to
be detached from an object explicitly:
.PP
.Vb 1
\&  $f\-> file( undef);
.Ve
.PP
However, if the system detects that a file handle is no longer valid,
it is automatically detached. It is possible to check, if a file handle
is still valid by calling the \f(CW\*(C`is_active()\*(C'\fR method.
.PP
Prima::File events are basically the same I/O callbacks, provided by
a system \f(CW\*(C`select()\*(C'\fR call. See documentation of your system's \fIselect()\fR
for the implementation details.
.SH "API"
.IX Header "API"
.SS "Properties"
.IX Subsection "Properties"
.IP "file \s-1HANDLE\s0" 4
.IX Item "file HANDLE"
Selects a file handle, that is to be monitored for stream I/O events.
If \s-1HANDLE\s0 is \f(CW\*(C`undef\*(C'\fR, object is returned to a passive state, and
the previously binded file handle is de-selected.
.IP "mask \s-1EVENT_MASK\s0" 4
.IX Item "mask EVENT_MASK"
Selects a event mask, that is a combination of \f(CW\*(C`fe::XXX\*(C'\fR integer constants,
each representing an event:
.Sp
.Vb 3
\&   fe::Read
\&   fe::Write
\&   fe::Exception
.Ve
.Sp
The omitted events are effectively excluded from the system file event
multiplexing mechanism.
.SS "Methods"
.IX Subsection "Methods"
.IP "get_handle" 4
.IX Item "get_handle"
Returns \f(CW\*(C`sprintf("0x%08x", fileno( file ))\*(C'\fR string.
If \f(CW\*(C`::file\*(C'\fR is \f(CW\*(C`undef\*(C'\fR, \-1 is used instead \fIfileno()\fR result.
.IP "is_active \s-1AUTODETACH\s0 = 0" 4
.IX Item "is_active AUTODETACH = 0"
Returns a boolean flag, indicating if a file handle is valid.
If \s-1AUTODETACH\s0 is 1, and the file handle is not valid, 
\&\f(CW\*(C`file(undef)\*(C'\fR is called.
.SS "Events"
.IX Subsection "Events"
.IP "Read" 4
.IX Item "Read"
Called when a file handle becomes readable. The callback procedure
is expected to call a non-blocking \fIread()\fR on the file handle.
.IP "Write" 4
.IX Item "Write"
Called when a file handle becomes writable. The callback procedure
is expected to call a non-blocking \fIwrite()\fR on the file handle.
.IP "Exception" 4
.IX Item "Exception"
Called when an exception is signaled on a file handle.
The exceptions are specific to handle type and the operating system.
For example, a unix socket signals \f(CW\*(C`Exception\*(C'\fR when a control status 
data for a pseudo terminal or an out-of-band data arrives.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Object