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