view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        "$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 check "$handle->end_of_input".

        EINTR is handled internally.

        Example:

         ($array, $sub, $hash)=$handle->read_record;

    $handle->end_of_input
        When an end of file condition is read this is set to true.

    ($pid, $uid, $gid)=$handle->peercred
        ONLY FOR UNIX DOMAIN SOCKETS ON LINUX

        Return the PID, eUID and eGID of the peer at the time of the
        connect.

    $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.

  Exceptions
    *   "IO::Handle::Record: sysread"

        thrown in "read_record". Check $! for more information.

    *   "IO::Handle::Record: premature end of file"

        thrown in "read_record" on end of file if according to the internal
        protocol more input is expected.

    *   "IO::Handle::Record: busy"

        thrown in "write_record" if a non-blocking write is not yet
        finished. There may be only one write operation at a time. If that
        hits you organise a queue.

    *   "IO::Handle::Record: syswrite"

        thrown in "write_record" on an error of the underlying transport
        method. Check $! for more information.

    *   Other exceptions

        thrown in "read_record" and "write_record" if something cannot be
        encoded or decoded by the "Storable" module. If that hits you the
        "Storable" module at one side is probably too old.

  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.

    If there are file descriptors to be passed they are sent by a separate
    sendmsg call along with 2 length fields only.

    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
    * credential passing over UNIX domain sockets

SEE ALSO