IPC::MorseSignals - Communicate between processes with Morse signals.
VERSION
- Version 0.01
+ Version 0.07
SYNOPSIS
use IPC::MorseSignals qw/msend mrecv/;
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;
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 $rcv = 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"
+ mlastsender $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, "<perl at profvince.com>"
projects / perl / modules / IPC-MorseSignals.git / blobdiff