NAME¶
IO::Pipely - Portably create pipe() or pipe-like handles, one way or another.
VERSION¶
version 0.005
SYNOPSIS¶
Please read DESCRIPTION for detailed semantics and caveats.
use IO::Pipely qw(pipely socketpairly);
# Create a one-directional pipe() or pipe-like thing
# the best conduit type available.
my ($read, $write) = pipely();
# Create a one-directional pipe-like thing using an
# INET socket specifically. Other types are available.
my ($read, $write) = pipely(type => 'inet');
# Create a bidirectional pipe-like thing using
# the best conduit type available.
my (
$side_a_read, $side_b_read,
$side_a_write, $side_b_write,
) = socketpairly();
# Create a bidirectional pipe-like thing using an INET socket
# specifically.
my (
$side_a_read, $side_b_read,
$side_a_write, $side_b_write,
) = socketpairly(type => 'inet');
DESCRIPTION¶
Pipes are troublesome beasts because there are a few different, incompatible
ways to create them. Not all platforms support all ways, and some platforms
may have hidden difficulties like incomplete or buggy support.
IO::Pipely provides a couple functions to portably create one- and two-way pipes
and pipe-like socket pairs. It acknowledges and works around known platform
issues so you don't have to.
On the other hand, it doesn't work around unknown issues, so please report any
problems early and often.
IO::Pipely currently understands
pipe(), UNIX-domain
socketpair()
and regular IPv4 localhost sockets. This covers every platform tested so far,
but it's hardly complete. Please help support other mechanisms, such as
INET-domain
socketpair() and IPv6 localhost sockets.
IO::Pipely will use different kinds of pipes or sockets depending on the
operating system's capabilities and the number of directions requested. The
autodetection may be overridden by specifying a particular pipe type.
pipely¶
pipely() creates a one-directional
pipe() or socket. It's modeled
after Perl's built-in
pipe() function, but it creates and returns
handles rather than opening ones given to it.
On success,
pipely() returns two file handles, the first to read from the
pipe, and the second writes into the pipe. It returns nothing on failure.
use IO::Pipely qw(pipely);
my ($a_read, $b_write) = pipely();
die "pipely() failed: $!" unless $a_read;
When given a choice, it will prefer to use leaner
pipe() calls instead of
socketpair() and
socket().
pipely()'s choice can be forced using an optional named "type"
parameter. See "PIPE TYPES" for the types that can be used.
my ($a_read, $b_write) = pipely(
type => 'pipe',
);
On most systems,
pipely() will prefer to open a
pipe() first. It
will fall back to a UNIX
socketpair() or two localhost Internet
sockets, in that order.
On Windows (ActiveState and Strawberry Perl),
pipely() prefers two
localhost Internet sockets. It will fall back to
socketpair() and
pipe(), both of which will probably fail.
Cygwin Perl prefers
pipe() first, localhost Internet sockets, and then
socketpair().
socketpair() has been known to have problems on
Cygwin.
MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
socketpairly¶
socketpairly() creates a two-directional socket pair. It's modeled after
Perl's built-in
socketpair(), but it creates and returns handles rather
than opening ones given to it.
On success,
socketpairly() returns four file handles, read and write for
one end, and read and write for the other. On failure, it returns nothing.
use IO::Pipely qw(socketpairly);
my ($a_read, $b_read, $a_write, $b_write) = socketpairly();
die "socketpairly() failed: $!" unless $a_read;
socketpairly() returns two extra "writer" handles. They exist
for the fallback case where two
pipe() calls are needed instead of one
socket pair. The extra handles can be ignored whenever
pipe() will
never be used. For example:
use IO::Pipely qw(socketpairly);
my ($side_a, $side_b) = socketpairly( type => 'socketpair' );
die "socketpairly() failed: $!" unless $side_a;
When given a choice, it will prefer bidirectional sockets instead of
pipe() calls.
socketpairly()'s choice can be forced using an optional named
"type" parameter. See "PIPE TYPES" for the types that can
be used. In this example, two unidirectional pipes wil be used instead of a
more efficient pair of sockets:
my ($a_read, $a_write, $b_read, $b_write) = pipely(
type => 'pipe',
);
On most systems,
socketpairly() will try to open a UNIX
socketpair() first. It will then fall back to a pair of localhost
Internet sockets, and finally it will try a pair of
pipe() calls.
On Windows (ActiveState and Strawberry Perl),
socketpairly() prefers a
pair of localhost Internet sockets first. It will then fall back to a UNIX
socketpair(), and finally a couple of
pipe() calls. The fallback
options will probably fail, but the code remains hopeful.
Cygwin Perl prefers localhost Internet sockets first, followed by a pair of
pipe() calls, and finally a UNIX
socketpair(). Those who know
may find this counter-intuitive, but it works around known issues in some
versions of Cygwin
socketpair().
MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
PIPE TYPES¶
IO::Pipely currently supports three types of pipe and socket. Other types are
possible, but these three cover all known uses so far. Please ask (or send
patches) if additional types are needed.
pipe
Attempt to establish a one-way pipe using one
pipe() filehandle pair (2
file descriptors), or a two-way pipe-like connection using two
pipe()
pairs (4 file descriptors).
IO::Pipely prefers to use
pipe() for one-way pipes and some form of
socket pair for two-way pipelike things.
socketpair
Attempt to establish a one- or two-way pipelike connection using a single
socketpair() call. This uses two file descriptors regardless whether
the connection is one- or two-way.
IO::Pipely prefers
socketpair() for two-way connections, unless the
current platform has known issues with the
socketpair() call.
Socket pairs are UNIX domain only for now. INET domain may be added if it
improves compatibility on some platform, or if someone contributes the code.
inet
Attempt to establish a one- or two-way pipelike connection using localhost
socket() calls. This uses two file descriptors regardless whether the
connection is one- or two-way.
Localhost INET domain sockets are a last resort for platforms that don't support
something better. They are the least secure method of communication since
tools like tcpdump and Wireshark can tap into them. On the other hand, this
makes them easiest to debug.
KNOWN ISSUES¶
These are issues known to the developers at the time of this writing. Things
change, so check back now and then.
Cygwin¶
CygWin seems to have a problem with
socketpair() and
exec(). When
an exec'd process closes, any data on sockets created with
socketpair()
is not flushed. From irc.perl.org channel #poe:
<dngnand> Sounds like a lapse in cygwin's exec implementation.
It works ok under Unix-ish systems?
<jdeluise2> yes, it works perfectly
<jdeluise2> but, if we just use POE::Pipe::TwoWay->new("pipe")
it always works fine on cygwin
<jdeluise2> by the way, it looks like the reason is that
POE::Pipe::OneWay works because it tries to make a
pipe first instead of a socketpair
<jdeluise2> this socketpair problem seems like a long-standing
one with cygwin, according to searches on google,
but never been fixed.
MacOS 9¶
IO::Pipely supports MacOS 9 for historical reasons. It's unclear whether anyone
still uses MacPerl, but the support is cheap since pipes and sockets there
have many of the same caveats as they do on Windows.
Symbol::gensym¶
IO::Pipely uses
Symbol::gensym() instead of autovivifying file handles.
The main reasons against
gensym() have been stylistic ones so far.
Meanwhile,
gensym() is compatible farther back than handle
autovivification.
Windows¶
ActiveState and Strawberry Perl don't support
pipe() or UNIX
socketpair(). Localhost Internet sockets are used for everything there,
including one-way pipes.
For one-way pipes, the unused socket directions are shut down to avoid sending
data the wrong way through them. Use
socketpairly() instead.
BUGS¶
The functions implemented here die outright upon failure, requiring eval{}
around their calls.
The following conduit types are currently unsupported because nobody has needed
them so far. Please submit a request (and/or a patch) if any of these is
needed:
UNIX socket()
INET-domain socketpair()
IPv4-specific localhost sockets
IPv6-specific localhost sockets
AUTHOR & COPYRIGHT¶
IO::Pipely is copyright 2000-2013 by Rocco Caputo. All rights reserved.
IO::Pipely is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.
HISTORY¶
IO::Pipely is a spin-off of the POE project's portable pipes. Earlier versions
of the code have been tested and used in production systems for over a
decade.