NAME
    IO::Socket::SIPC - Serialize perl structures for inter process
    communication.

SYNOPSIS
        use IO::Socket::SIPC;

DESCRIPTION
    This module makes it possible to transport perl structures between
    processes over sockets. It wrappes your favorite IO::Socket module and
    controls the amount of data over the socket. The default serializer is
    Storable with "nfreeze()" and "thaw()" but you can choose each other
    serializer you wish to use. You have just follow some restrictions and
    need only some lines of code to adjust it for yourself. In addition it's
    possible to use a checksum to check the integrity of the transported
    data. Take a look to the method section.

METHODS
  new()
    Call "new()" to create a new IO::Socket::SIPC object.

        favorite        Set your favorite module - IO::Socket::(INET|UNIX|SSL).
        deflate         Pass your own sub reference for serializion.
        inflate         Pass your own sub reference for deserializion.
        read_max_bytes  Set the maximum allowed bytes to read from the socket.
        send_max_bytes  Set the maximum allowed bytes to send over the socket.
        use_check_sum   Check each transport with a MD5 sum.
        gen_check_sum   Set up your own checksum generator.

    Defaults

        favorite        IO::Socket::INET
        deflate         nfreeze() of Storable
        inflate         thaw() of Storable (in a Safe compartment)
        read_max_bytes  unlimited
        send_max_bytes  unlimited
        gen_check_sum   md5() of Digest::MD5
        use_check_sum   enabled (disable it with 0)

    Set your favorite socket handler:

        use IO::Socket::SIPC;

        my $sipc = IO::Socket::SIPC->new( favorite => 'IO::Socket::SSL' );

    Set your own serializer:

        use IO::Socket::SIPC;
        use Convert::Bencode_XS;

        my $sipc = IO::Socket::SIPC->new(
            deflate => sub { Convert::Bencode_XS::bencode($_[0]) },
            inflate => sub { Convert::Bencode_XS::bdecode($_[0]) },
        );

        # or maybe

        use IO::Socket::SIPC;
        use JSON::PC;

        my $sipc = IO::Socket::SIPC->new(
            deflate => sub { JSON::PC::convert($_[0]) },
            inflate => sub { JSON::PC::parse($_[0])   },
        );

    NOTE that the code that you handoff with deflate and inflate is embed in
    an eval block and if it an error occurs you can get the error string by
    calling "errstr()". If you use the default deserializer of Storable then
    the data is deserialized in a Safe compartment. If you use another
    deserializer you have to build your own Safe compartment within your
    code ref!

    Use your own checksum generator (dummy example):

        my $sipc = IO::Socket::SIPC->new(
           gen_check_sum => sub { Your::Fav::gen_sum($_[0]) }
        );

    But I think Digest::MD5 is very well and it does it's job.

  read_max_bytes() and send_max_bytes()
    Call both methods to increase or decrease the maximum bytes that the
    server or client is allowed to "read()" or "send()". Possible sizes are
    KB, MB and GB or just a number for bytes. It's not case sensitiv and you
    can use "KB" or "kb" or just "k". If you want set the readable or
    sendable size to unlimited then you can call both methods with 0 or
    "unlimited". The default max send and read size is unlimited.

    Here some notations examples

        $sipc->read_max_bytes(1048576);
        $sipc->read_max_bytes('1024k');
        $sipc->read_max_bytes('1MB');

        # unlimited
        $sipc->read_max_bytes('unlimited');
        $sipc->read_max_bytes(0);

    NOTE that the readable and sendable size is computed by the serialized
    and deserialized data or on the raw data if you use "read_raw()" or
    "send_raw()".

  connect()
    Call "connect()" to connect to the socket. "connect()" just call "new()"
    of your favorite and handoff all params to it. Example:

        my $sipc = IO::Socket::SIPC->new( favorite => 'IO::Socket::INET' );

        $sipc->connect(
           PeerAddr => 'localhost',
           PeerPort => '50010',
           Proto    => 'tcp',
        );

        # would call intern

        IO::Socket::INET->new(@_);

  accept()
    If a Listen socket is defined then you can wait for connections with
    "accept()". "accept()" is just a wrapper to the original "accept()"
    method of your favorite. If a connection is accepted then a new object
    is created related to the peer. The new object will be returned on
    success, undef on error and 0 on a timeout.

    You can set a timeout value in seconds.

        my $c = $sipc->accept(10)
        warn "accept: timeout" if defined $c;

  disconnect()
    Call "disconnect()" to disconnect the current connection. "disconnect()"
    calls "close()" on the socket that is referenced by the object.

  sock()
    Call "sock()" to access the raw object of your favorite module.

    IO::Socket::INET examples:

        $sipc->sock->timeout(10);
        # or
        $peerhost = $sipc->sock->peerhost;
        # or
        $peerport = $sipc->sock->peerport;
        # or
        $sock = $sipc->sock;
        $peerhost = $sock->peerhost;

    NOTE that if you use

        while ( my $c = $sipc->sock->accept ) { ... }

    that $c is the unwrapped IO::Socket::* object and not a IO::Socket::SIPC
    object.

  send()
    Call "send()" to send data over the socket to the peer. The data will be
    serialized and packed before it sends to the peer. If you use the
    default serializer then you must handoff a reference, otherwise an error
    occure because "nfreeze()" of Storable just works with references.

        $sipc->send("Hello World!");  # this would fail
        $sipc->send(\"Hello World!"); # this not

    If you use your own serializer then consult the documentation for what
    the serializer expect.

    "send()" returns undef on errors or if send_max_bytes is overtaken.

  read()
    Call "read()" to read data from the socket. The data will be unpacked
    and deserialized before it is returned. If the maximum read bytes is
    overtaken or an error occured then "read()" returns undef and aborts to
    read from the socket.

  read_raw() and send_raw()
    If you want to read or send a raw string and disable the serializer for
    a single transport then you can call "read_raw()" or "send_raw()".

  errstr()
    Call "errstr()" to get the current error message if a method returns
    undef. "errstr()" is not useable with "new()" because "new()" croaks by
    wrong settings.

    NOTE that "errstr()" returns the current error message that contain $!
    if necessary. If you use IO::Socket::SSL then the message from
    IO::Socket::SSL->errstr is appended as well.

  debug()
    You can turn on a little debugger if you like

        $sipc->debug(1);

    The debugger will set IO::Socket::SSL::DEBUG as well if you use it.

EXAMPLES
    Take a look to the examples directory.

  Server example
  Client example
PREREQUISITES
        UNIVERSAL::require  -  to post load favorite modules
        IO::Socket::INET    -  to create sockets
        Digest::MD5         -  to check the data before and after transports
        Storable            -  the default serializer and deserializer
        Safe                -  deserialize (Storable::thaw) in a safe compartment

EXPORTS
    No exports.

REPORT BUGS
    Please report all bugs to <jschulz.cpan(at)bloonix.de>.

AUTHOR
    Jonny Schulz <jschulz.cpan(at)bloonix.de>.

QUESTIONS
    Do you have any questions or ideas?

    MAIL: <jschulz.cpan(at)bloonix.de>

    IRC: irc.perl.org#perlde

TODO AND IDEAS
        * do you have any ideas?
        * maybe another implementations of check sum generators
        * do you like to have another wrapper as accept()? Tell me!
        * auto authentification

COPYRIGHT
    Copyright (C) 2007 by Jonny Schulz. All rights reserved.

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