X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=098eddf457353ae2aa83e48538170180019c97c6;hb=5231a0009f35e98b287dc9633b67bb1de52a23ab;hp=221958f3a234d00a6ec8fa4cbbee6f846168432d;hpb=3cadc28babc49dbbb76ef7ff7344add68f59c3c2;p=perl%2Fmodules%2FIPC-MorseSignals.git diff --git a/README b/README index 221958f..098eddf 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME IPC::MorseSignals - Communicate between processes with Morse signals. VERSION - Version 0.01 + Version 0.06 SYNOPSIS use IPC::MorseSignals qw/msend mrecv/; @@ -11,7 +11,10 @@ SYNOPSIS if (!defined $pid) { die "fork() failed: $!"; } elsif ($pid == 0) { - local @SIG{qw/USR1 USR2/} = mrecv sub { print STDERR "recieved $_[0]!\n" }; + my $s = mrecv local %SIG, cb => sub { + print STDERR "received $_[1] from $_[0]!\n"; + exit + }; 1 while 1; } msend "hello!\n" => $pid; @@ -19,43 +22,108 @@ SYNOPSIS DESCRIPTION This module implements a rare form of IPC by sending Morse-like signals - through "SIGUSR1" and "SIGUSR2". It uses both signals "SIGUSR1" and - "SIGUSR2", so you won't be able to keep them for something else when you - use this module. + through "SIGUSR1" and "SIGUSR2". Both of those signals are used, so you + won't be able to keep them for something else when you use this module. But, seriously, use something else for your IPC. :) FUNCTIONS "msend" - msend $msg, $pid [, $speed ] + msend $msg, $pid [, speed => $speed, utf8 => $utf8, sign => $sign ] Sends the string $msg to the process $pid (or to all the processes @$pid if $pid is an array ref) at $speed bits per second. Default speed is - 1000, don't set it too low or the target will miss bits and the whole - message will be crippled. + 512, don't set it too low or the target will miss bits and the whole + message will be crippled. If the "utf8" flag is set (default is unset), + the string will first be encoded in UTF-8. The "utf8" bit of the packet + message is turned on, so that the receiver is aware of it. If the "sign" + flag is unset (default is set), the PID of the sender won't be shipped + with the packet. "mrecv" - mrecv $callback + mrecv %SIG [, cb => $callback ] - Takes as its sole argument the callback triggered when a complete - message is received, and returns two code references that should replace - SIGUSR1 and SIGUSR2 signal handlers. Basically, you want to use it like - this : + Takes as its first argument the %SIG hash and returns a hash reference + that represent the current state of the receiver. %SIG's fields 'USR1' + and 'USR2' will be replaced by the receiver's callbacks. "cb" specifies + the callback to trigger each time a complete message has arrived. + Basically, you want to use it like this : - local @SIG{qw/USR1 USR2/} = mrecv sub { ... }; + my $rv = mrecv local %SIG, cb => sub { ... }; + + In the callback, $_[0] is the sender's PID (or 0 if the sender wanted to + stay anonymous) and $_[1] is the message received. + + "mreset" + mreset $rcv + + Resets the state of the receiver $rcv. Useful to abort transfers. + + "mbusy" + mbusy $rcv + + Returns true if the receiver $rcv is currently busy with incoming data, + or false otherwise. + + "mlastsender" + mlastmsg $rcv + + Holds the PID of the last process that sent data to the receiver $rcv, 0 + if that process was anonymous, or "undef" if no message has arrived yet. + It isn't cleared by "mreset". + + "mlastmsg" + mlastmsg $rcv + + Holds the last message received by $rcv, or "undef" if no message has + arrived yet. It isn't cleared by "mreset". EXPORT - This module exports on request its two only functions, "msend" and - "mrecv". + This module exports any of its functions only on request. + +PROTOCOL + Each byte of the data string is converted into its bits sequence, with + bits of highest weight coming first. All those bits sequences are put + into the same order as the characters occur in the string. + + The header is composed by the "utf8" bit (if the data has to be decoded + to UTF-8), the "sign" bit (if sender gives its PID in the header), and + then 24 bits representing the sender's PID (with highest weight coming + first) if the "sign" bit is set. + + The emitter computes then the longuest sequence of successives 0 (say, + m) and 1 (n) in the concatenation of the header and the data. A + signature is then chosen : + + - If m > n, we take n+1 times 1 follewed by one 0 ; + - Otherwise, we take m+1 times 0 follewed by one 1. + + The signal is then formed by concatenating the signature, the header, + the data bits and the reversed signature (i.e. the bits of the signature + in the reverse order). + + a ... a b | u s [ p23 ... p0 ] | ... data ... | b a ... a + signature | header | data | reversed signature + + The receiver knows that the signature has been sent when it has catched + at least one 0 and one 1. The signal is completely transferred when it + has received for the first time the whole reversed signature. + +CAVEATS + This type of IPC is highly unreliable. Send little data at slow speed if + you want it to reach its goal. + + "SIGUSR{1,2}" seem to interrupt sleep, so it's not a good idea to + transfer data to a sleeping process. DEPENDENCIES - POSIX (standard since perl 5) and Time::HiRes (standard since perl - 5.7.3) are required. + Carp (standard since perl 5), POSIX (idem), Time::HiRes (since perl + 5.7.3) and utf8 (since perl 5.6) are required. SEE ALSO - perlipc for information about signals. + perlipc for information about signals in perl. - For truely useful IPC, search for shared memory, pipes and semaphores. + For truly useful IPC, search for shared memory, pipes and semaphores. AUTHOR Vincent Pit, ""