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 bounded 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, bound 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 When a file handle is not needed anymore, it is expected to be detached
54 from an object explicitly:
55 $f-> file( undef);
57 However, if the system detects that a file handle is no longer valid,
59 it is automatically detached. It is possible to check, if a file handle
60 is still valid by calling the is_active() method.
61 Prima::File events are basically the same I/O callbacks, provided by a
63 system select() call. See documentation of your system's select() for
64 the implementation details.
65
67 Properties
68 file HANDLE
69 Selects a file handle, that is to be monitored for stream I/O
70 events. If HANDLE is "undef", object is returned to a passive
71 state, and the previously bonded file handle is de-selected.
72 If the OS reports an error when attaching the file, f ex because
74 there are too many objects to monitor, the file handle is reverted
75 to "undef". Use that to check for an error.
76 fd INTEGER
78 Same as file(), but to be used for file descriptors. When this
79 property is used, consequent get-calls to file() will return undef.
80 If the OS reports an error when attaching the file, f ex because
82 there are too many objects to monitor, the file handle is reverted
83 to "undef". Use that to check for an error.
84 mask EVENT_MASK
86 Selects a event mask, that is a combination of "fe::XXX" integer
87 constants, each representing an event:
88 fe::Read
90 fe::Write
91 fe::Exception
92 The omitted events are effectively excluded from the system file
94 event multiplexing mechanism.
95 Methods
97 get_handle
98 Returns "sprintf("0x%08x", fileno( file ))" string. If "::file" is
99 "undef", -1 is used instead fileno() result.
100 is_active AUTODETACH = 0
102 Returns a boolean flag, indicating if a file handle is valid. If
103 AUTODETACH is 1, and the file handle is not valid, file(undef) is
104 called.
105 Events
107 Read
108 Called when a file handle becomes readable. The callback procedure
109 is expected to call a non-blocking read() on the file handle.
110 Write
112 Called when a file handle becomes writable. The callback procedure
113 is expected to call a non-blocking write() on the file handle.
114 Exception
116 Called when an exception is signaled on a file handle. The
117 exceptions are specific to handle type and the operating system.
118 For example, a unix socket signals "Exception" when a control
119 status data for a pseudo terminal or an out-of-band data arrives.
120
122 Unix
123 Prima can monitor max FD_SETSIZE file handles (not Prima::File objects,
124 these can refer to same file handles just fine). See also "man 2
125 select".
126 Win32
128 Files
129 If Prima detects that a handle is neither a socket nor a console,
130 it assumes that it is a "regular" file. Prima doesn't use any win32
131 api for checking on regular file handle availability for reading
132 and writing, and therefore sends synthetic events without actual
133 correlation whether the file handle is actually readable or
134 writable.
135 Pipes
137 Pipe handles are not implemented and won't work.
138 Sockets
140 Sockets work natively, however there's a single catch: according to
141 the MSDN, WSAEventSelect() sets sockets in a non-blocking mode,
142 however I couldn't confirm that when I was experimenting. If you
143 want to be 100% covered, remember and restore the blocking flag in
144 your event handlers.
145 There can be normally max 63 sockets (not Prima::File objects,
147 these can refer to same sockets just fine). Or max 62 sockets if
148 STDIN is monitored too. See also
149 <https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-msgwaitformultipleobjectsex>
150 .
151 STDIN
153 STDIN works fine when it is a console. Use
154 "Prima::sys::win32::ReadConsoleInput" for detailed input parsing.
155 See also
156 <https://learn.microsoft.com/en-us/windows/console/readconsoleinputex>.
157
159 Dmitry Karasik, <dmitry@karasik.eu.org>.
160
162 Prima, Prima::Object
163perl v5.38.0 2023-07-21 pod::Prima::File(3)