Debian Codegraph @

README

raw
1 NAME
2
3 IO::Pipely - Portably create pipe() or pipe-like handles, one way or
4 another.
5
6 SYNOPSIS
7
8 Please read DESCRIPTION for detailed semantics and caveats.
9
10 use IO::Pipely qw(pipely socketpairly);
11
12 # Create a one-directional pipe() or pipe-like thing
13 # the best conduit type available.
14
15 my ($read, $write) = pipely();
16
17 # Create a one-directional pipe-like thing using an
18 # INET socket specifically. Other types are available.
19
20 my ($read, $write) = pipely(type => 'inet');
21
22 # Create a bidirectional pipe-like thing using
23 # the best conduit type available.
24
25 my (
26 $side_a_read, $side_a_write,
27 $side_b_read, $side_b_write,
28 ) = socketpairly();
29
30 # Create a bidirectional pipe-like thing using an INET socket
31 # specifically.
32
33 my (
34 $side_a_read, $side_a_write,
35 $side_b_read, $side_b_write,
36 ) = socketpairly(type => 'inet');
37
38 DESCRIPTION
39
40 Pipes are troublesome beasts because there are a few different,
41 incompatible ways to create them. Not all platforms support all ways,
42 and some platforms may have hidden difficulties like incomplete or
43 buggy support.
44
45 IO::Pipely provides a couple functions to portably create one- and
46 two-way pipes and pipe-like socket pairs. It acknowledges and works
47 around known platform issues so you don't have to.
48
49 On the other hand, it doesn't work around unknown issues, so please
50 report any problems early and often.
51
52 IO::Pipely currently understands pipe(), UNIX-domain socketpair() and
53 regular IPv4 localhost sockets. This covers every platform tested so
54 far, but it's hardly complete. Please help support other mechanisms,
55 such as INET-domain socketpair() and IPv6 localhost sockets.
56
57 IO::Pipely will use different kinds of pipes or sockets depending on
58 the operating system's capabilities and the number of directions
59 requested. The autodetection may be overridden by specifying a
60 particular pipe type.
61
62 pipely
63
64 pipely() creates a one-directional pipe() or socket. It's modeled after
65 Perl's built-in pipe() function, but it creates and returns handles
66 rather than opening ones given to it.
67
68 On success, pipely() returns two file handles, the first to read from
69 the pipe, and the second writes into the pipe. It returns nothing on
70 failure.
71
72 use IO::Pipely qw(pipely);
73 my ($a_read, $b_write) = pipely();
74 die "pipely() failed: $!" unless $a_read;
75
76 When given a choice, it will prefer to use leaner pipe() calls instead
77 of socketpair() and socket().
78
79 pipely()'s choice can be forced using an optional named "type"
80 parameter. See "PIPE TYPES" for the types that can be used.
81
82 my ($a_read, $b_write) = pipely(
83 type => 'pipe',
84 );
85
86 On most systems, pipely() will prefer to open a pipe() first. It will
87 fall back to a UNIX socketpair() or two localhost Internet sockets, in
88 that order.
89
90 On Windows (ActiveState and Strawberry Perl), pipely() prefers two
91 localhost Internet sockets. It will fall back to socketpair() and
92 pipe(), both of which will probably fail.
93
94 Cygwin Perl prefers pipe() first, localhost Internet sockets, and then
95 socketpair(). socketpair() has been known to have problems on Cygwin.
96
97 MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
98
99 socketpairly
100
101 socketpairly() creates a two-directional socket pair. It's modeled
102 after Perl's built-in socketpair(), but it creates and returns handles
103 rather than opening ones given to it.
104
105 On success, socketpairly() returns four file handles, read and write
106 for one end, and read and write for the other. On failure, it returns
107 nothing.
108
109 use IO::Pipely qw(socketpairly);
110 my ($a_read, $a_write, $b_read, $b_write) = socketpairly();
111 die "socketpairly() failed: $!" unless $a_read;
112
113 socketpairly() returns two extra "writer" handles. They exist for the
114 fallback case where two pipe() calls are needed instead of one socket
115 pair. The extra handles can be ignored whenever pipe() will never be
116 used. For example:
117
118 use IO::Pipely qw(socketpairly);
119 my ($side_a, undef, $side_b, undef) = socketpairly( type => 'socketpair' );
120 die "socketpairly() failed: $!" unless $side_a;
121
122 When given a choice, it will prefer bidirectional sockets instead of
123 pipe() calls.
124
125 socketpairly()'s choice can be forced using an optional named "type"
126 parameter. See "PIPE TYPES" for the types that can be used. In this
127 example, two unidirectional pipes wil be used instead of a more
128 efficient pair of sockets:
129
130 my ($a_read, $a_write, $b_read, $b_write) = socketpairly(
131 type => 'pipe',
132 );
133
134 On most systems, socketpairly() will try to open a UNIX socketpair()
135 first. It will then fall back to a pair of localhost Internet sockets,
136 and finally it will try a pair of pipe() calls.
137
138 On Windows (ActiveState and Strawberry Perl), socketpairly() prefers a
139 pair of localhost Internet sockets first. It will then fall back to a
140 UNIX socketpair(), and finally a couple of pipe() calls. The fallback
141 options will probably fail, but the code remains hopeful.
142
143 Cygwin Perl prefers localhost Internet sockets first, followed by a
144 pair of pipe() calls, and finally a UNIX socketpair(). Those who know
145 may find this counter-intuitive, but it works around known issues in
146 some versions of Cygwin socketpair().
147
148 MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
149
150 PIPE TYPES
151
152 IO::Pipely currently supports three types of pipe and socket. Other
153 types are possible, but these three cover all known uses so far. Please
154 ask (or send patches) if additional types are needed.
155
156 pipe
157
158 Attempt to establish a one-way pipe using one pipe() filehandle pair (2
159 file descriptors), or a two-way pipe-like connection using two pipe()
160 pairs (4 file descriptors).
161
162 IO::Pipely prefers to use pipe() for one-way pipes and some form of
163 socket pair for two-way pipelike things.
164
165 socketpair
166
167 Attempt to establish a one- or two-way pipelike connection using a
168 single socketpair() call. This uses two file descriptors regardless
169 whether the connection is one- or two-way.
170
171 IO::Pipely prefers socketpair() for two-way connections, unless the
172 current platform has known issues with the socketpair() call.
173
174 Socket pairs are UNIX domain only for now. INET domain may be added if
175 it improves compatibility on some platform, or if someone contributes
176 the code.
177
178 inet
179
180 Attempt to establish a one- or two-way pipelike connection using
181 localhost socket() calls. This uses two file descriptors regardless
182 whether the connection is one- or two-way.
183
184 Localhost INET domain sockets are a last resort for platforms that
185 don't support something better. They are the least secure method of
186 communication since tools like tcpdump and Wireshark can tap into them.
187 On the other hand, this makes them easiest to debug.
188
189 KNOWN ISSUES
190
191 These are issues known to the developers at the time of this writing.
192 Things change, so check back now and then.
193
194 Cygwin
195
196 CygWin seems to have a problem with socketpair() and exec(). When an
197 exec'd process closes, any data on sockets created with socketpair() is
198 not flushed. From irc.perl.org channel #poe:
199
200 <dngnand> Sounds like a lapse in cygwin's exec implementation.
201 It works ok under Unix-ish systems?
202 <jdeluise2> yes, it works perfectly
203 <jdeluise2> but, if we just use POE::Pipe::TwoWay->new("pipe")
204 it always works fine on cygwin
205 <jdeluise2> by the way, it looks like the reason is that
206 POE::Pipe::OneWay works because it tries to make a
207 pipe first instead of a socketpair
208 <jdeluise2> this socketpair problem seems like a long-standing
209 one with cygwin, according to searches on google,
210 but never been fixed.
211
212 MacOS 9
213
214 IO::Pipely supports MacOS 9 for historical reasons. It's unclear
215 whether anyone still uses MacPerl, but the support is cheap since pipes
216 and sockets there have many of the same caveats as they do on Windows.
217
218 Symbol::gensym
219
220 IO::Pipely uses Symbol::gensym() instead of autovivifying file handles.
221 The main reasons against gensym() have been stylistic ones so far.
222 Meanwhile, gensym() is compatible farther back than handle
223 autovivification.
224
225 Windows
226
227 ActiveState and Strawberry Perl don't support pipe() or UNIX
228 socketpair(). Localhost Internet sockets are used for everything there,
229 including one-way pipes.
230
231 For one-way pipes, the unused socket directions are shut down to avoid
232 sending data the wrong way through them. Use socketpairly() instead.
233
234 BUGS
235
236 The functions implemented here die outright upon failure, requiring
237 eval{} around their calls.
238
239 The following conduit types are currently unsupported because nobody
240 has needed them so far. Please submit a request (and/or a patch) if any
241 of these is needed:
242
243 UNIX socket()
244 INET-domain socketpair()
245 IPv4-specific localhost sockets
246 IPv6-specific localhost sockets
247
248 AUTHOR & COPYRIGHT
249
250 IO::Pipely is copyright 2000-2021 by Rocco Caputo. All rights reserved.
251 IO::Pipely is free software; you may redistribute it and/or modify it
252 under the same terms as Perl itself.
253
254 HISTORY
255
256 IO::Pipely is a spin-off of the POE project's portable pipes. Earlier
257 versions of the code have been tested and used in production systems
258 for over a decade.
259