GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
pod::Prima::File(3) User Contributed Perl Documentation pod::Prima::File(3)

Prima::File - asynchronous stream I/O.

  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;

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.

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.

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.
fd INTEGER
Same as file(), but to be used for file descriptiors. When this property is used, consequent get-calls to file() will return undef.
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.

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.

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.

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

Prima, Prima::Object
2022-04-07 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.