/ 
IPC-MorseSignals-0.09
River stage zero No dependents
/ IPC::MorseSignals

NAME

IPC::MorseSignals - Communicate between processes with Morse signals.

VERSION

Version 0.09

SYNOPSIS

use IPC::MorseSignals qw/msend mrecv/;

my $pid = fork;
if (!defined $pid) {
 die "fork() failed: $!";
} elsif ($pid == 0) {
 my $s = mrecv local %SIG, cb => sub {
  print STDERR "received $_[1] from $_[0]!\n";
  exit
 };
 1 while 1;
}
msend "hello!\n" => $pid;
waitpid $pid, 0;

DESCRIPTION

This module implements a rare form of IPC by sending Morse-like signals 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 => $speed, 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 512, don't set it too low or the target will miss bits and the whole message will be crippled. If the sign flag is unset (default is set), the PID of the sender won't be shipped with the packet. UTF-8 encoded strings are automatically detected. The utf8 bit of the packet message is turned on, so that the receiver can encode them appropriately.

mrecv

mrecv %SIG [, cb => $callback ]

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 :

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 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 followed by one 0 ;
- Otherwise, we take m+1 times 0 followed 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

Carp (standard since perl 5), POSIX (idem), utf8 (since perl 5.6), Encode (since perl 5.7.3) and Time::HiRes (idem) are required.

SEE ALSO

perlipc for information about signals in perl.

For truly useful IPC, search for shared memory, pipes and semaphores.

AUTHOR

Vincent Pit, <perl at profvince.com>

You can contact me by mail or on #perl @ FreeNode (Prof_Vince).

BUGS

Please report any bugs or feature requests to bug-ipc-morsesignals at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-MorseSignals. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc IPC::MorseSignals

ACKNOWLEDGEMENTS

Thanks for the inspiration, mofino ! I hope this module will fill all your IPC needs. :)

COPYRIGHT & LICENSE

Copyright 2007 Vincent Pit, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.