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.

INSTALLATION
     perl Makefile.PL
     make
     make test
     make install

DEPENDENCIES
    *   perl 5.8.0

    *   Storable 2.05

    *   Class::Member 1.3