NAME

       Prima::File - asynchronous stream I/O.

SYNOPSIS

         use strict;
         use Prima qw(Application);

         # create pipe and autoflush the writer end
         pipe(READ, WRITE) or die "pipe():$!\n";
         select WRITE;
         $|=1;
         select STDOUT;

         # create Prima listener on the reader end
         my $read = Prima::File-> new(
             file => \*READ,
             mask => fe::Read,
             onRead => sub {
                $_ = <READ>;
                print "read:$_\n";
             },
         );

         print WRITE "line\n";
         run Prima;

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.

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:

         my $f = Prima::File-> create();
         $f-> file( *STDIN);

       When a file handle, binded via the "::file" property becomes readable, writable or when an exception
       signaled, one of three correspondent events called - "Read", "Write" or "Exception". 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 "::mask" property:

         $f-> mask( fe::Read | fe::Exception);

       NB. 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 socket.pl
       elucidates the use of sockets together with Prima::File.

       When a file handle is not needed anymore, it is expected to be detached from an object explicitly:

         $f-> file( undef);

       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 "is_active()" method.

       Prima::File events are basically the same I/O callbacks, provided by a system "select()" call. See
       documentation of your system's select() for the implementation details.

API

   Properties
       file HANDLE
           Selects  a  file handle, that is to be monitored for stream I/O events.  If HANDLE is "undef", object
           is returned to a passive state, and the previously binded file handle is de-selected.

       mask EVENT_MASK
           Selects a event mask, that is a combination of "fe::XXX"  integer  constants,  each  representing  an
           event:

              fe::Read
              fe::Write
              fe::Exception

           The omitted events are effectively excluded from the system file event multiplexing mechanism.

   Methods
       get_handle
           Returns  "sprintf("0x%08x",  fileno(  file  ))"  string.   If "::file" is "undef", -1 is used instead
           fileno() result.

       is_active AUTODETACH = 0
           Returns a boolean flag, indicating if a file handle is valid.  If  AUTODETACH  is  1,  and  the  file
           handle is not valid, "file(undef)" is called.

   Events
       Read
           Called when a file handle becomes readable. The callback procedure is expected to call a non-blocking
           read() on the file handle.

       Write
           Called when a file handle becomes writable. The callback procedure is expected to call a non-blocking
           write() on the file handle.

       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 "Exception" when a control status  data
           for a pseudo terminal or an out-of-band data arrives.

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

       Prima, Prima::Object

perl v5.22.1                                       2009-02-24                                pod::Prima::File(3)