IO::Events - Non-blocking IO using events
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;
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.
IO::Events::Loop
IO::Events::Handle
handle
IO::Handle
on_read
on_write
on_exception
on_create
on_close
on_error
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:
new
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.
IO::Select
IPC::Open
Set $SIG{PIPE} = 'IGNORE', usually a sound idea.
$SIG{PIPE} = 'IGNORE'
Set $|=1 first in your script if you use ::Fork or ::Process classes.
$|=1
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.
on_fork
die
exit
POSIX::exit
new()
Number of seconds passed to select() as the fourth parameter.
Default value: 50
In addition to select(), IO::Events::Loop also waits for finished processes, automatically getting rid of handles associated with them, if set to 1.
select()
Default value: 1
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.
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,
'block_read'
'block_write'
'block_exc'
$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.
Flushes write sockets, if possible.
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.
{id}
Hash of file numbers, read-only.
Hash of PIDs associated with handles, read-only. Used for IPC and waitpid results processing.
waitpid
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.
destroy
If set to 1, IO handle is explicitly closed as the object instance is destroyed. Doesn't affect anything otherwise.
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.
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.
nonblock
fcntl
Set to 1 if handle is to be read from.
Default value: 0
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.
IO::Events::Fork::ReadWrite
IO::Event::IPC::Process::ReadWrite
'read'
'write'
Set to 1 if handle is to be written from.
If a handle is associated with a process, IO::Events::Loop uses this field to waitpid() and auto-destruct the handle.
waitpid()
Default value: undef
Selects whether the handle is readable.
Selects whether the handle is writable.
Selects whether the handle accepts exception events.
Returns newline-ended read data, if available.
Return contents of the read buffer.
Appends DATA to the write buffer
Destructs handle instance
Dispatches EVENT, passing PARAMETERS to each callback.
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.
%events
SINGLE
MULTIPLE
{event_flag}
IO::Events::Handle::on_error
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.
Called after object instance is created.
Called when read or write calls encounter error.
Called when exception is arrived. Consult your system select manpage to see what events and on what socket types can be expected.
select
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.
IO::Events::Fork
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.
POSIX::_exit
Called after data is read.
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.
write
Runs a process with its stdout tied to a newly created handle. The process name is passed to process parameter to the new() contructor.
process
Runs a process with its stdin tied to a newly created handle. The process name is passed to process parameter to the new() contructor.
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.
Forks a child with its stdout tied to a newly created handle.
Forks a child with its stdin tied to a newly created handle.
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.
Shortcut class for STDIN handle.
Shortcut class for STDOUT handle.
Shortcut class for STDERR handle.
Shortcut class for TCP socket. Parameters accepted:
If set, connect() call is issued on the socket to HOSTNAME and port set in port parameter.
connect()
port
If set, socket listens on port.
Number of a port to bind to.
If set, socket listens on addr IP address, otherwise INADDR_ANY.
addr
Creates a new IO handle and accepts a connection into it. Returns the newly created IO::Events::Handle object with %PROFILE fields.
%PROFILE
Shortcut class for UDP socket. Parameters accepted:
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.
oob
dontroute
eor
eof
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.
peek
waitall
maxlen
A handle class, used to connect to and listen on UNIX sockets.
Connects to a socket over a given PATHNAME
Listens on a socket over a given PATHNAME
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.
IO::Event::Handle
owner
Invokes on_tick callback in SECONDS, which can be float.
on_tick
If on, timer is started immediately, otherwise is stopped.
If on, timer fires off event each SECONDS interval, otherwise goes off after the first on_tick.
Starts the timer
Stops the timer
Callback invoked each time SECONDS interval is expired.
perlipc, POE, IO::Handle, IO::Select, IPC::Open2.
Copyright (c) 2004 catpipe Systems ApS. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Dmitry Karasik <dmitry@karasik.eu.org>
To install IO::Events, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Events
CPAN shell
perl -MCPAN -e shell install IO::Events
For more information on module installation, please visit the detailed CPAN module installation guide.