X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=b2925f0b79ceef9541351852cb7a7bc8fe2f2fc5;hb=fcfeb2180a98d41e14a848f7bb8ba0d05b297c52;hp=221958f3a234d00a6ec8fa4cbbee6f846168432d;hpb=3cadc28babc49dbbb76ef7ff7344add68f59c3c2;p=perl%2Fmodules%2FIPC-MorseSignals.git diff --git a/README b/README index 221958f..b2925f0 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME IPC::MorseSignals - Communicate between processes with Morse signals. VERSION - Version 0.01 + Version 0.05 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" }; + local @SIG{qw/USR1 USR2/} = mrecv sub { + print STDERR "received $_[0]!\n"; + exit + }; 1 while 1; } msend "hello!\n" => $pid; @@ -19,43 +22,72 @@ 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 ] 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. + if $pid is an array ref) at $speed bits per second. If the "utf8" flag + is set, the string will first be encoded in UTF-8. In this case, you + must turn it on for "mrecv" as well. Default speed is 512, don't set it + too low or the target will miss bits and the whole message will be + crippled. The "utf8" flag is turned off by default. "mrecv" - mrecv $callback + mrecv $callback [, utf => $utf8 ] - Takes as its sole argument the callback triggered when a complete + Takes as its first 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 + "USR1" and "USR2" signal handlers. Basically, you want to use it like this : local @SIG{qw/USR1 USR2/} = mrecv sub { ... }; + Turn on the utf8 flag if you know that the incoming strings are expected + to be in UTF-8. This flag is turned off by default. + EXPORT This module exports on request its two only functions, "msend" and "mrecv". +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 emitter + computes then the longuest sequence of successives 0 (say, m) and 1 (n). + 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 data bits + and the reversed signature (i.e. the bits of the signature in the + reverse order). + + 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, ""