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