NAME IO::Handle::Record - IO::Handle extension to pass perl data structures SYNOPSIS use IO::Socket::UNIX; use IO::Handle::Record; ($p, $c)=IO::Socket::UNIX->socketpair( AF_UNIX, SOCK_STREAM, PF_UNSPEC ); while( !defined( $pid=fork ) ) {sleep 1} if( $pid ) { close $c; undef $c; $p->fds_to_send=[\*STDIN, \*STDOUT]; $p->record_opts={send_CODE=>1}; $p->write_record( {a=>'b', c=>'d'}, sub { $_[0]+$_[1] }, [qw/this is a test/] ); } else { close $p; undef $p; $c->record_opts={receive_CODE=>sub {eval $_[0]}}; ($hashref, $coderef, $arrayref)=$c->read_record; readline $c->received_fds->[0]; # reads from the parent's STDIN } INSTALLATION perl Makefile.PL make make test make install DEPENDENCIES * perl 5.8.0 * Storable 2.05 * Class::Member 1.3 DESCRIPTION "IO::Handle::Record" extends the "IO::Handle" class. Since many classes derive from "IO::Handle" these extensions can be used with "IO::File", "IO::Socket", "IO::Pipe", etc. The methods provided read and write lists of perl data structures. They can pass anything that can be serialized with "Storable" even subroutines between processes. The following methods are added: $handle->record_opts This lvalue method expects a hash reference with options as parameter. The "send_CODE" and "receive_CODE" options correspond to localized versions of $Storable::Deparse and $Storable::Eval respectively. Using them Perl code can be passed over a connection. See the Storable manpage for further information. In a few cases IO::Handle::Record passes binary data over the connection. Normally network byte order is used there. You can save a few CPU cycles if you set the "local_encoding" option to true. In this case the byte order of the local machine is used. Example: $handle->record_opts={send_CODE=>1, receive_CODE=>1, local_encoding=>1}; $handle->fds_to_send=\@fds Called before "write_record" sets a list of file handles that are passed to the other end of a UNIX domain stream socket. The next "write_record" transfers them as open files. So the other process can read or write to them. @fds=@{$handle->received_fds} This is the counterpart to "fds_to_send". After a successful "read_record" the receiving process can fetch the transferred handles from this list. The handles are GLOBs blessed to one of: * IO::File * IO::Dir * IO::Pipe * IO::Socket::UNIX * IO::Socket::INET * IO::Socket::INET6 * IO::Handle according to their type. "IO::Handle" is used as kind of catchall type. Open devices are received as such. "IO::Handle::Record" does not load all of these modules. That's up to you. $handle->write_record(@data) writes a list of perl data structures. "write_record" returns 1 if the record has been transmitted. "undef" is returned if $handle is non blocking and a EAGAIN condition is met. In this case reinvoke the operation without parameters (just "$handle->write_record") when the handle becomes ready. Otherwise it throws an exception "IO::Handle::Record: syswrite error". Check $! in this case. EINTR is handled internally. Example: $handle->write_record( [1,2], sub {$_[0]+$_[1]}, { list=>[1,2,3], hash=>{a=>'b'}, code=>sub {print "test\n";} } ); @data=$handle->read_record reads one record of perl data structures. On success it returns the record as list. An empty list is returned if $handle is in non blocking mode and not enough data has been read. Check $!==EAGAIN to catch this condition. When the handle becomes ready just repeat the operation to read the next data chunk. If a complete record has arrived it is returned. On EOF an empty list is returned. To distinguish this from the non blocking empty list return set "$!=0" before the operation and check for "$!==EAGAIN" after. EINTR is handled internally. Example: ($array, $sub, $hash)=$handle->read_record; $handle->read_buffer $handle->expected $handle->expect_fds $handle->_received_fds $handle->write_buffer $handle->written these methods are used internally to provide a read and write buffer for non blocking operations. EXPORT None. Data Transfer Format The Perl data is serialized using Storable::freeze or Storable::nfreeze. Storable::freeze is used if the "local_encoding" option is set, Storable::nfreeze otherwise. The length in bytes of this data chunk and the number of file handles that are passed along with the data are then each "pack()"ed as a 4 byte binary value using the "L" or "N" template. "L" is used of "local_encoding" is in effect. Both fields is the prepended to the data chunk: +-----------------+------------------------+ | data length (N) | number of file handles | | 4 bytes | 4 bytes | +-----------------+------------------------+ | | | | | | | | | data | | | | N bytes | | | | | | | | | | | +------------------------------------------+ WARNING: The transfer format has changed in version 0.07 (never made it to CPAN) and again in version 0.08. TODO * compression * encryption * credential passing over UNIX domain sockets SEE ALSO "IO::Handle" AUTHOR Torsten Foertsch, COPYRIGHT AND LICENSE Copyright (C) 2005-2008 by Torsten Foertsch This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.