NAME IO::Socket::SIPC - Serialize perl structures for inter process communication. SYNOPSIS use IO::Socket::SIPC; my $sipc = IO::Socket::SIPC->new( favorite => 'IO::Socket::INET', use_check_sum => 1, read_may_bytes => '512k', send_may_bytes => '512k' ); $sipc->connect( LocalAddr => $address, LocalPort => $port, Proto => $proto, Listen => $listen, ReuseAddr => $reuse, ) or die $sipc->errstr; my $client = $sipc->accept($timeout); my %perl_struct = ( hash => { foo => 'bar' }, array => [ 'foo', 'bar' ], ); $client->send( \%perl_struct ); DESCRIPTION This module makes it possible to transport perl structures between processes. It wrappes your favorite IO::Socket module and controls the amount of data and verifies it with a checksum. The default serializer is Storable with "nfreeze()" and "thaw()" and the default checksum generator is Digest::MD5 with "md5()" but you can choose any other serializer or checksum generator you wish to use, there are just some restrictions that you have to comply with and you only need to adjust a few lines of code by yourself. METHODS new(\%config) The "new()" constructor method creates a new IO::Socket::SIPC object. A list of parameters as a hash or a hash reference may be passed to it. 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. The defaults are: favorite IO::Socket::INET deflate nfreeze() of Storable inflate thaw() of Storable (in a Safe compartment) read_max_bytes unlimited send_max_bytes unlimited use_check_sum disabled (enable it with 1) gen_check_sum md5() of Digest::MD5 if use_check_sum is enabled favorite Set your favorite socket handler - IO::Socket::INET, IO::Socket::UNIX or IO::Socket::SSL. use IO::Socket::SIPC; my $sipc = IO::Socket::SIPC->new( favorite => 'IO::Socket::SSL' ); deflate, inflate 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 to deflate and inflate is embedded in an eval block for executions and if 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_check_sum Turn it on (1) or off (0) for the current object. If you turn it on then a checksum is generated for any packet that is transportet. The default checksum generator is "md5()" of Digest::MD5. gen_check_sum Use your own checksum generator: use Digest::SHA2; my $sha2obj = new Digest::SHA2; my $sipc = IO::Socket::SIPC->new( gen_check_sum => sub { $sha2obj->digest($_[0]) } ); But I think Digest::MD5 is very well and it does it's job. read_max_bytes, send_max_bytes Increase or decrease the maximum size of bytes that a peer is allowed to send or read. 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". Notations: # 1 MB read_max_bytes => 1048576 read_max_bytes => '1024k' read_max_bytes => '1MB' # unlimited read_max_bytes => 0 read_max_bytes => unlimited 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(@_); You can pass all params that are allowed of your favorite. I don't check it. 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; is_timeout() Another check if you want to know if "accept()" return FALSE because a timeout happends. while ( 1 ) { while ( my $c = $sipc->accept(10) ) { # processing } warn "accept: timeout" if $sipc->is_timeout; } disconnect() Call "disconnect()" to disconnect the current connection. "disconnect()" calls "close()" on the socket that is referenced by the object. my $c = $sipc->accept(); $c->disconnect; # to close $c $sipc->disconnect; # to close $sipc 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 occurs 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's returned. If the maximum 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()". Note that "read_raw()" and "send_raw()" doesn't work with references! errstr() Call "errstr()" to get the current error message if a method returns FALSE. "errstr()" is not useable with "new()" because "new()" croaks with incorrect arguments. NOTE that "errstr()" returns the current error message and 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); It you use IO::Socket::SSL then $IO::Socket::SSL::DEBUG is set to level that you passed with "debug()". 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 . AUTHOR Jonny Schulz . QUESTIONS Do you have any questions or ideas? MAIL: 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.