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->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;
}

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 are defined. They correspond to localized versions of $Storable::Deparse and $Storable::Eval respectively. See the Storable manpage for further information.

Example:

$handle->record_opts={send_CODE=>1, receive_CODE=>1};

$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 =item $handle->expected =item $handle->write_buffer =item $handle->written

these methods are used internally to provide a read and write buffer for non blocking operations.

EXPORT

None.

SEE ALSO

IO::Handle

AUTHOR

Torsten Foertsch, <torsten.foertsch@gmx.net<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Torsten Foertsch

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