NAME

    IO::Pipely - Portably create pipe() or pipe-like handles, one way or
    another.

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_a_write,
        $side_b_read, $side_b_write,
      ) = socketpairly();
    
      # Create a bidirectional pipe-like thing using an INET socket
      # specifically.
    
      my (
        $side_a_read, $side_a_write,
        $side_b_read, $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, $a_write, $b_read, $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, undef, $side_b, undef) = 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) = socketpairly(
        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-2021 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.