pod::Prima::File(3pm)

1pod::Prima::File(3)   User Contributed Perl Documentation  pod::Prima::File(3)
2
3
4

NAME

6       Prima::File - asynchronous stream I/O.
7

SYNOPSIS

9         use strict;
10         use Prima qw(Application);
11
12         # create pipe and autoflush the writer end
13         pipe(READ, WRITE) or die "pipe():$!\n";
14         select WRITE;
15         $|=1;
16         select STDOUT;
17
18         # create Prima listener on the reader end
19         my $read = Prima::File-> new(
20             file => \*READ,
21             mask => fe::Read,
22             onRead => sub {
23                $_ = <READ>;
24                print "read:$_\n";
25             },
26         );
27
28         print WRITE "line\n";
29         run Prima;
30

DESCRIPTION

32       Prima::File provides access to the I/O stream events, that are called
33       when a file handle becomes readable, writable or if an exception
34       occurred. Registering file handles to Prima::File objects makes
35       possible the stream operations coexist with the event loop.
36

USAGE

38       Prima::File is a descendant of Prima::Component.  Objects of
39       Prima::File class must be bounded to a valid file handle object, before
40       the associated events can occur:
41
42         my $f = Prima::File-> create();
43         $f-> file( *STDIN);
44
45       When a file handle, blinded via the "::file" property becomes readable,
46       writable or when an exception signaled, one of three correspondent
47       events called - "Read", "Write" or "Exception". When a handle is always
48       readable, or always writable, or, some of these events are desired to
49       be blocked, the file event mask can be set via the "::mask" property:
50
51         $f-> mask( fe::Read | fe::Exception);
52
53       NB. Due to different system implementations, the only handles,
54       currently supported on all systems, are socket handle and disk file
55       handles. Pipes only work on unix platforms. The example file socket.pl
56       elucidates the use of sockets together with Prima::File.
57
58       When a file handle is not needed anymore, it is expected to be detached
59       from an object explicitly:
60
61         $f-> file( undef);
62
63       However, if the system detects that a file handle is no longer valid,
64       it is automatically detached. It is possible to check, if a file handle
65       is still valid by calling the is_active() method.
66
67       Prima::File events are basically the same I/O callbacks, provided by a
68       system select() call. See documentation of your system's select() for
69       the implementation details.
70

API

72   Properties
73       file HANDLE
74           Selects a file handle, that is to be monitored for stream I/O
75           events.  If HANDLE is "undef", object is returned to a passive
76           state, and the previously bonded file handle is de-selected.
77
78       fd INTEGER
79           Same as file(), but to be used for file descriptors. When this
80           property is used, consequent get-calls to file() will return undef.
81
82       mask EVENT_MASK
83           Selects a event mask, that is a combination of "fe::XXX" integer
84           constants, each representing an event:
85
86              fe::Read
87              fe::Write
88              fe::Exception
89
90           The omitted events are effectively excluded from the system file
91           event multiplexing mechanism.
92
93   Methods
94       get_handle
95           Returns "sprintf("0x%08x", fileno( file ))" string.  If "::file" is
96           "undef", -1 is used instead fileno() result.
97
98       is_active AUTODETACH = 0
99           Returns a boolean flag, indicating if a file handle is valid.  If
100           AUTODETACH is 1, and the file handle is not valid, file(undef) is
101           called.
102
103   Events
104       Read
105           Called when a file handle becomes readable. The callback procedure
106           is expected to call a non-blocking read() on the file handle.
107
108       Write
109           Called when a file handle becomes writable. The callback procedure
110           is expected to call a non-blocking write() on the file handle.
111
112       Exception
113           Called when an exception is signaled on a file handle.  The
114           exceptions are specific to handle type and the operating system.
115           For example, a unix socket signals "Exception" when a control
116           status data for a pseudo terminal or an out-of-band data arrives.
117

Win32 implementation

119       On windows (but not on cygwin), file handles do not report I/O events,
120       only sockets and consoles do. All other handles are assumed to be
121       inherently readable and writable, and if one is subscribed to these
122       events, they are fired non-stop, so event  warning with event flooding
123       here.
124

AUTHOR

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