Provided by: libio-pipely-perl_0.005-1_all 
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.