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 notIf 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 compartmentEXPORTS
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 authentificationCOPYRIGHT
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.