---
name: "Prima::File"
section: "3"
platform: "linux"
package: "libprima-perl"
version: "1.28-1.3+b3"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Prima::File"
---

# Prima::File(3)

asynchronous stream I/O.

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