NAME

IO::Events - Non-blocking IO using events

SYNOPSIS

Example 1, run 'bc' as a co-process:

        use IO::Events;

        my $loop = IO::Events::Loop-> new();

        my $stdin_alive = 1;
        my $calculator = IO::Events::Process::ReadWrite-> new(
                owner    => $loop,
                process  => 'bc -l', 
                on_read  => sub {
                        while ( my $line = $_[0]-> readline) {
                                print "bc says: $line";
                        }
                },
                on_close => sub {
                        exit 1 if $stdin_alive; # fork/exec error
                }
        );

        my $stdin = IO::Events::stdin-> new(
                owner => $loop,
                on_read => sub { 
                $calculator-> write( $_[0]-> read );
                },
                on_close => sub {
                        $stdin_alive = 0;
                        exit;
                },
        );

        $loop-> yield while 1;

Example 2, connect to/listen on a TCP port within a single process:

        use IO::Events;
        
        my $loop = IO::Events::Loop-> new();
        IO::Events::Socket::TCP-> new(
                owner    => $loop,
                listen   => 1,
                port     => 10000,
                on_read => sub {
                        my $new = shift-> accept( 
                                read   => 1,
                                on_read => sub {
                                        while ( my $line = $_[0]-> readline) {
                                                print "client says: $line\n";
                                                exit;
                                        }
                                }
                        );
                        print "connect from $new->{remote_addr}:$new->{remote_port}\n";
                },
        );
        
        IO::Events::Socket::TCP-> new(
                owner   => $loop,
                connect => 'localhost',
                port    => 10000,
        )-> write("hello, tcp socket!\n");
        
        $loop->yield while 1;

Example 3, connect to/listen on a UDP port within a single process:

        use Socket;
        use IO::Events;
        
        my $loop = IO::Events::Loop-> new();
        IO::Events::Socket::UDP-> new(
                owner    => $loop,
                port     => 10000,
                on_read => sub {
                        my $self = $_[0];
                        my $data = $self-> recv;
                        print "$self->{remote_host}:$self->{remote_port} says: $data";
                        exit;
                },
        );
        
        IO::Events::Socket::UDP-> new(
                owner   => $loop,
        )-> send( 'localhost', 10000, "hello, udp socket!\n");
        
        $loop->yield while 1;

DESCRIPTION

The module implements object-oriented approach to select-driven events and contains set of convenience objects for inter-process communication.

The main part of the module is the 'loop' instance of IO::Events::Loop class, which knows about all IO handles subject to select(). The handles are inherited from IO::Events::Handle class, which property handle holds reference to a IO handle object, - a file scalar or IO::Handle instance. IO::Events::Handle object propagates select-based events - on_read, on_write, on_exception, as well as generic on_create, on_close and on_error. It is a requirement that handles are non-blocking.

All instances are created by calling new with arbitrary number of named parameters. The unrecognized parameters are stored in the object and cause no conflict:

        my $a = IO::Events::Handle-> new( my_var => 1 );
        die $a->{my_var};

The module is not meant to serve as replacement of IO::Select and IPC::Open, and can perfectly live together with the first and counteract with the handles managed by the second. The example in "SYNOPSIS" section displays how to harness the non-blocking IO between stdin and a co-process.

Advices

Set $SIG{PIPE} = 'IGNORE', usually a sound idea.
Set $|=1 first in your script if you use ::Fork or ::Process classes.
If you use on_fork, never terminate a child process by die or exit, because otherwise everything Perl allocated in parent process will be de-allocated twice, both in the parent and in the child process. If you must, use POSIX::exit instead.

IO::Events::Loop

`new()` parameters

timeout INTEGER

Number of seconds passed to select() as the fourth parameter.

Default value: 50

waitpid BOOLEAN

In addition to select(), IO::Events::Loop also waits for finished processes, automatically getting rid of handles associated with them, if set to 1.

Default value: 1

Methods

handles

Returns number of handles owner by loop object. When a program automatically disposes of handles, not needed anymore, it may choose to stop when there are no more handles to serve.

yield %HASH

Enters select() loop and dispatches pending IO if data are available to read or write. Hash values of 'block_read', 'block_write', and 'block_exc' can be set to 1 if read, write, or exception events are not to be used. Practically,

        $loop-> yield( block_read => 1, block_exc => 1, timeout => 0 )

call effectively ( but still in the non-blocking fashion ) flushes write buffers.

Returns result of select() call, the number of streams handled.

flush

Flushes write sockets, if possible.

Fields

%id: All handles are assigned an unique id, and are stored in internal {id} hash. This hash is read-only, and can be used to look-up a handle object by its id string.
%filenos: Hash of file numbers, read-only.
%processes: Hash of PIDs associated with handles, read-only. Used for IPC and waitpid results processing.

IO::Events::Handle

Root of IO handle object hierarchy, dispatches IO events and auto-destructs when handle is closed or an IO error occurs. The explicit destruction is invoked by calling destroy, which is reentrant-safe.

Parameters to `new()`

auto_close BOOLEAN

If set to 1, IO handle is explicitly closed as the object instance is destroyed. Doesn't affect anything otherwise.

Default value: 1

flush [ DISCARD = 0]

Flushes not yet written data. If DISCARD is 1, does not return until all data are written or error is signalled. If 0, discards all data.

handle IOHANDLE

IO::Handle object or a file scalar. If not specified, a new IO::Handle instance is created automatically.

The handle is set to non-blocking mode. If this is already done, nonblock optional boolean parameter can be set to 1 to prevent extra fcntl calls.

read BOOLEAN

Set to 1 if handle is to be read from.

Default value: 0

shutdown @WHO

Defined in IO::Events::Fork::ReadWrite and IO::Event::IPC::Process::ReadWrite namespaces. @WHO can contain string 'read' and 'write', to tell what part of bidirectional IPC is to be closed.

write BOOLEAN

Set to 1 if handle is to be written from.

Default value: 0

pid INTEGER

If a handle is associated with a process, IO::Events::Loop uses this field to waitpid() and auto-destruct the handle.

Default value: undef

Methods

can_read BOOLEAN: Selects whether the handle is readable.
can_write BOOLEAN: Selects whether the handle is writable.
can_exception BOOLEAN: Selects whether the handle accepts exception events.
readline: Returns newline-ended read data, if available.
read: Return contents of the read buffer.
write DATA: Appends DATA to the write buffer
destroy: Destructs handle instance
notify $EVENT, @PARAMETERS: Dispatches EVENT, passing PARAMETERS to each callback.

Events

A single event can cause several callback routines to be called. This is useful when a class declares its own, for example, cleanup code in on_close sub, whereas the class instance user can add another listener to the same on_close notification:

        package MyHandle;
        ...
        sub on_close { ... }
        ...

        MyHandle-> new( on_close => sub { ... });

The class declares static ( per-class ) instance of hash %events, which contains declaration of events and their execution flow. SINGLE-declared events call only single callback, be it static or dynamic. MULTIPLE-declared events call all callbacks, but execution flow can be stopped by setting {event_flag} to 1. This is useful, for example, to dynamically override default behavior of IO::Events::Handle::on_error which emits a warning message to stderr and destroys the handle.

on_close

Called before object instance is destroyed.

In a special case for ReadWrite objects, on_close is called twice, when read and write handles are closed. To distinuish between the cases, the second parameter is set to 1 when on_close is called due to the writer handle destruction.

Declared as MULTIPLE.

on_create

Called after object instance is created.

Declared as MULTIPLE.

on_error

Called when read or write calls encounter error.

Declared as MULTIPLE.

on_exception

Called when exception is arrived. Consult your system select manpage to see what events and on what socket types can be expected.

on_fork

Special event, called by IO::Events::Fork objects when a new process is instantiated. Although the syntax for specifying on_fork is the same as for the other events, on_fork does not interact with these, and is not called from within yield.

When on_fork returned, process is terminated. If you wish to terminate process yourself, do not call perl's exit but rather POSIX::_exit, since otherwise perl stuctures created before fork will be destroyed twice.

on_read

Called after data is read.

on_write

Called when handle is writable and the write buffer is empty. If the event doesn't fill the write buffer, the handle write flag is cleared and further on_write notifications are suppressed until the write buffer is filled.

IO::Events::Process::Read

Runs a process with its stdout tied to a newly created handle. The process name is passed to process parameter to the new() contructor.

IO::Events::Process::Write

Runs a process with its stdin tied to a newly created handle. The process name is passed to process parameter to the new() contructor.

IO::Events::Process::ReadWrite

Runs a process with its stdin and stdout tied to two newly created handles. The both handles are transparently mapped to a single handle object.

Note: check IPC::Open2 and IPC::Open3 also.

IO::Events::Fork::Read

Forks a child with its stdout tied to a newly created handle.

IO::Events::Fork::Write

Forks a child with its stdin tied to a newly created handle.

IO::Events::Fork::ReadWrite

Forks a child with its stdin and stdout tied to two newly created handles. The both handles are transparently mapped to a single handle object.

IO::Events::stdin

Shortcut class for STDIN handle.

IO::Events::stdout

Shortcut class for STDOUT handle.

IO::Events::stderr

Shortcut class for STDERR handle.

IO::Events::Socket::TCP

Shortcut class for TCP socket. Parameters accepted:

connect HOSTNAME: If set, connect() call is issued on the socket to HOSTNAME and port set in port parameter.
listen: If set, socket listens on port.
port INTEGER: Number of a port to bind to.
addr STRING: If set, socket listens on addr IP address, otherwise INADDR_ANY.
accept %PROFILE: Creates a new IO handle and accepts a connection into it. Returns the newly created IO::Events::Handle object with %PROFILE fields.

IO::Events::Socket::UDP

Shortcut class for UDP socket. Parameters accepted:

port INTEGER

Number of a port to bind to.

addr STRING

If set, socket listens on addr IP address, otherwise INADDR_ANY.

send HOSTNAME, PORT, DATA, %OPTIONS

Issues send(2) call, returns number of bytes sent or an error. See "send" in perldoc for more details.

Options accepted: oob, dontroute, eor, eof.

recv %OPTIONS

Issues recv(2) call, returns data block or under if error. See "recv" in perldoc for more details.

Options accepted: oob, peek, waitall, nonblock, maxlen.

IO::Events::Socket::UNIX

A handle class, used to connect to and listen on UNIX sockets.

accept %PROFILE: Creates a new IO handle and accepts a connection into it. Returns the newly created IO::Events::Handle object with %PROFILE fields.
connect PATHNAME: Connects to a socket over a given PATHNAME
listen PATHNAME: Listens on a socket over a given PATHNAME

IO::Events::Timer

A tiny hackish hask to add time-based events. The class is not inherited from IO::Event::Handle, and the only property it shared with the other handle classes is owner.

timeout SECONDS: Invokes on_tick callback in SECONDS, which can be float.
active BOOLEAN: If on, timer is started immediately, otherwise is stopped.
repetitive BOOLEAN: If on, timer fires off event each SECONDS interval, otherwise goes off after the first on_tick.
start: Starts the timer
stop: Stops the timer
on_tick: Callback invoked each time SECONDS interval is expired.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Dmitry Karasik <dmitry@karasik.eu.org>

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Advices

IO::Events::Loop

new() parameters

Methods

Fields

IO::Events::Handle

Parameters to new()

Methods

Events

IO::Events::Process::Read

IO::Events::Process::Write

IO::Events::Process::ReadWrite

IO::Events::Fork::Read

IO::Events::Fork::Write

IO::Events::Fork::ReadWrite

IO::Events::stdin

IO::Events::stdout

IO::Events::stderr

IO::Events::Socket::TCP

IO::Events::Socket::UDP

IO::Events::Socket::UNIX

IO::Events::Timer

SEE ALSO

COPYRIGHT

AUTHOR

Module Install Instructions

`new()` parameters

Parameters to `new()`