1pod::Prima::File(3) User Contributed Perl Documentation pod::Prima::File(3)
2
6 Prima::File - asynchronous stream I/O.
7
9 use strict;
10 use Prima qw(Application);
11 # create pipe and autoflush the writer end
13 pipe(READ, WRITE) or die "pipe():$!\n";
14 select WRITE;
15 $|=1;
16 select STDOUT;
17 # 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 print WRITE "line\n";
29 run Prima;
30
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
38 Prima::File is a descendant of Prima::Component. Objects of
39 Prima::File class must be binded to a valid file handle object, before
40 the associated events can occur:
41 my $f = Prima::File-> create();
43 $f-> file( *STDIN);
44 When a file handle, binded 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 $f-> mask( fe::Read | fe::Exception);
52 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 When a file handle is not needed anymore, it is expected to be detached
59 from an object explicitly:
60 $f-> file( undef);
62 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 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
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 binded file handle is de-selected.
77 fd INTEGER
79 Same as file(), but to be used for file descriptiors. When this
80 property is used, consequent get-calls to file() will return undef.
81 mask EVENT_MASK
83 Selects a event mask, that is a combination of "fe::XXX" integer
84 constants, each representing an event:
85 fe::Read
87 fe::Write
88 fe::Exception
89 The omitted events are effectively excluded from the system file
91 event multiplexing mechanism.
92 Methods
94 get_handle
95 Returns "sprintf("0x%08x", fileno( file ))" string. If "::file" is
96 "undef", -1 is used instead fileno() result.
97 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 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 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 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
119 Dmitry Karasik, <dmitry@karasik.eu.org>.
120
122 Prima, Prima::Object
123perl v5.34.1 2022-04-20 pod::Prima::File(3)