/ 
Prima-1.75
River stage two • 17 direct dependents • 19 total dependents
/ Prima::File

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 a 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

The Prima::File class provides access to the I/O stream notifications that are called when a file handle becomes readable, writable, or if an exception/out-of-band message occurs. Registering file handles to Prima::File objects makes it possible for the stream operations to coexist with the event loop.

USAGE

Prima::File is a descendant of Prima::Component. Objects of the Prima::File class must be bounded to a valid file handle object before the associated events can occur:

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

When a file handle bound via the ::file property becomes readable, writable, or when an exception/out-of-band message is signaled, one of three corresponding events is sent - Read, Write, or Exception. When the file handle is always readable, or always writable, or, on the contrary, 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);

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

$f-> file( undef);

However, if the system detects that the 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 based on the events provided by the select() function on unix or on the WSAEnumNetworkEvents function on Win32.

API

Properties

file HANDLE

Selects the file handle to be monitored for the I/O events. If the HANDLE is undef, the object is returned to the passive state, and the previously bonded file handle is de-selected.

If the OS reports an error when attaching the file, f ex because there are too many objects to monitor, the file handle is reverted to undef. Use that to check for an error.

fd INTEGER

Same as file(), but to be used for the file descriptors instead. When this property is used, consequent get-calls to file() will return undef.

If the OS reports an error when attaching the file, f ex because there are too many objects to monitor, the file handle is reverted to undef. Use that to check for an error.

mask EVENT_MASK

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

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

The masked 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 of the fileno() result.

is_active AUTODETACH = 0

Returns the boolean flag indicating if the file handle is valid. If AUTODETACH is 1 and the file handle is not valid file(undef) is called.

Events

Read

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

Write

Called when the 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 the file handle. The exceptions are specific to the handle type and the operating system. For example, a unix socket may signal the Exception event when control status data for a pseudoterminal or an out-of-band message arrives.

OS considerations

Unix

Prima can monitor max FD_SETSIZE file handles (not Prima::File objects, these can refer to the same file handles just fine). See also man 2 select.

Win32

Files

If Prima detects that the handle is neither a socket nor a console, it assumes that it is a regular file. Prima doesn't use any win32 api for checking on regular file handle availability for reading and writing and therefore sends synthetic events without actual correlation on whether the file handle is readable or writable.

Pipes

Pipe handles are not implemented and won't work.

Sockets

Sockets work natively, however, there's a single catch: according to the MSDN, WSAEventSelect() sets sockets in a non-blocking mode, however, I couldn't confirm that when I was experimenting. If you want to be 100% covered, remember to save and restore the blocking flag in your event handlers.

There can be normally a maximum of 63 sockets (not Prima::File objects, these can refer to the same sockets just fine). Or a maximum of 62 sockets if STDIN is monitored too. See also https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-msgwaitformultipleobjectsex .

STDIN

STDIN works fine when it is a console. Use Prima::sys::win32::ReadConsoleInput for detailed input parsing. See also https://learn.microsoft.com/en-us/windows/console/readconsoleinputex.

AUTHOR

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

SEE ALSO

Prima, Prima::Object