NAME

UniEvent::Pipe - abstraction over streaming files and named pipes

SYNOPSIS

        my $pipe = UniEvent::Pipe->new;
        $pipe->connect('/path/to/pipe', sub {
                my ($pipe, $err) = @_;
        die $err if $err;
        $pipe->write("hello");

        $pipe->read_callback(sub {
            my ($pipe, $data, $err) = @_;
            die $err if $err;
            say "got $data";
                $pipe->disconnect;
        });
        });

    # create pipe pair
    my ($reader, $writer) = UniEvent::Pipe::pair();
    
    $reader->read_callback(sub { ... });
    $writer->write("hello");

DESCRIPTION

Pipe handles provide an abstraction over streaming files on Unix (including local domain sockets, pipes, and FIFOs) and named pipes on Windows.

It is inherited from UniEvent::Stream, which provides most of the API.

FUNCTIONS

pair($reader, $writer)

pair([$loop = default])

Opens a pair of connected pipes like the corresponding system call.

In the first form, connects already existing objects. Objects must be in "clean" state (i.e. just created or after reset).

In the second form, creates two UniEvent::Pipe objects in $loop and connects them.

In either case, returns those two pipe objects.

    my ($reader, $writer) = UE::Pipe::pair();
    
    package MyPipe;
    use parent 'UniEvent::Pipe';
    
    my $reader = MyPipe->new;
    my $writer = MyPipe->new;
    UE::Pipe::pair($reader, $writer);

METHODS

All methods of UniEvent::Stream also apply.

new([$loop = default], [$ipc = false])

The $ipc argument is a boolean to indicate if this pipe will be used for handle passing between processes (which may change the bytes on the wire). Only a connected pipe that will be passing the handles should have this flag set, not the listening pipe.

open($fd, $mode)

Open an existing file descriptor $fd as a pipe. The $mode flag marks the connected state and type of the pipe end.

If fd is not connected, then $mode should be MODE_NOT_CONNECTED.

Otherwise, $mode should be either MODE_READABLE or MODE_WRITABLE depending on what the type of the pipe end is.

In case of connected unix socket, $mode should be a bitmask MODE_READABLE | MODE_WRITABLE

May return error

bind($name)

Bind the pipe to a file path (Unix) or a name (Windows). On windows it should be something like "\\\\.\\pipe\\$name".

May return error

NOTE: Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) bytes, typically between 92 and 108 bytes.

connect($name, [$callback])

Connect to the Unix domain socket or the named pipe. Optionally the $callback can be specified, which will be added as ->connect_event->add($callback).

See "connect_event()" in UniEvent::Stream for callback signature.

sockname()

Get the name of the Unix domain socket or the named pipe.

If pipe is not connected, empty string is returned.

May return error

peername()

Get the name of the Unix domain socket or the named pipe which the handle is connected to.

If pipe is not connected, empty string is returned.

May return error

pending_instances($count)

Set the number of pending pipe instance handles when the pipe server is waiting for connections. Applicable for Windows only.

chmod($mode)

Alters pipe permissions, allowing it to be accessed from processes run by different users. Makes the pipe writable or readable by all users. Mode can be MODE_WRITABLE, MODE_READABLE or MODE_WRITABLE | MODE_READABLE.

May return error

CONSTANTS

MODE_NOT_CONNECTED

MODE_READABLE

MODE_WRITABLE

cpanm UniEvent

perl -MCPAN -e shell
install UniEvent