README

   1 NAME
   2     IPC::MorseSignals - Communicate between processes with Morse signals.
   3
   4 VERSION
   5     Version 0.07
   6
   7 SYNOPSIS
   8         use IPC::MorseSignals qw/msend mrecv/;
   9
  10         my $pid = fork;
  11         if (!defined $pid) {
  12          die "fork() failed: $!";
  13         } elsif ($pid == 0) {
  14          my $s = mrecv local %SIG, cb => sub {
  15           print STDERR "received $_[1] from $_[0]!\n";
  16           exit
  17          };
  18          1 while 1;
  19         }
  20         msend "hello!\n" => $pid;
  21         waitpid $pid, 0;
  22
  23 DESCRIPTION
  24     This module implements a rare form of IPC by sending Morse-like signals
  25     through "SIGUSR1" and "SIGUSR2". Both of those signals are used, so you
  26     won't be able to keep them for something else when you use this module.
  27
  28     But, seriously, use something else for your IPC. :)
  29
  30 FUNCTIONS
  31   "msend"
  32         msend $msg, $pid [, speed => $speed, utf8 => $utf8, sign => $sign ]
  33
  34     Sends the string $msg to the process $pid (or to all the processes @$pid
  35     if $pid is an array ref) at $speed bits per second. Default speed is
  36     512, don't set it too low or the target will miss bits and the whole
  37     message will be crippled. If the "utf8" flag is set (default is unset),
  38     the string will first be encoded in UTF-8. The "utf8" bit of the packet
  39     message is turned on, so that the receiver is aware of it. If the "sign"
  40     flag is unset (default is set), the PID of the sender won't be shipped
  41     with the packet.
  42
  43   "mrecv"
  44         mrecv %SIG [, cb => $callback ]
  45
  46     Takes as its first argument the %SIG hash and returns a hash reference
  47     that represent the current state of the receiver. %SIG's fields 'USR1'
  48     and 'USR2' will be replaced by the receiver's callbacks. "cb" specifies
  49     the callback to trigger each time a complete message has arrived.
  50     Basically, you want to use it like this :
  51
  52         my $rcv = mrecv local %SIG, cb => sub { ... };
  53
  54     In the callback, $_[0] is the sender's PID (or 0 if the sender wanted to
  55     stay anonymous) and $_[1] is the message received.
  56
  57   "mreset"
  58         mreset $rcv
  59
  60     Resets the state of the receiver $rcv. Useful to abort transfers.
  61
  62   "mbusy"
  63         mbusy $rcv
  64
  65     Returns true if the receiver $rcv is currently busy with incoming data,
  66     or false otherwise.
  67
  68   "mlastsender"
  69         mlastsender $rcv
  70
  71     Holds the PID of the last process that sent data to the receiver $rcv, 0
  72     if that process was anonymous, or "undef" if no message has arrived yet.
  73     It isn't cleared by "mreset".
  74
  75   "mlastmsg"
  76         mlastmsg $rcv
  77
  78     Holds the last message received by $rcv, or "undef" if no message has
  79     arrived yet. It isn't cleared by "mreset".
  80
  81 EXPORT
  82     This module exports any of its functions only on request.
  83
  84 PROTOCOL
  85     Each byte of the data string is converted into its bits sequence, with
  86     bits of highest weight coming first. All those bits sequences are put
  87     into the same order as the characters occur in the string.
  88
  89     The header is composed by the "utf8" bit (if the data has to be decoded
  90     to UTF-8), the "sign" bit (if sender gives its PID in the header), and
  91     then 24 bits representing the sender's PID (with highest weight coming
  92     first) if the "sign" bit is set.
  93
  94     The emitter computes then the longuest sequence of successives 0 (say,
  95     m) and 1 (n) in the concatenation of the header and the data. A
  96     signature is then chosen :
  97
  98     - If m > n, we take n+1 times 1 follewed by one 0 ;
  99     - Otherwise, we take m+1 times 0 follewed by one 1.
 100
 101     The signal is then formed by concatenating the signature, the header,
 102     the data bits and the reversed signature (i.e. the bits of the signature
 103     in the reverse order).
 104
 105         a ... a b | u s [ p23 ... p0 ] | ... data ... | b a ... a
 106         signature |      header        |     data     | reversed signature
 107
 108     The receiver knows that the signature has been sent when it has catched
 109     at least one 0 and one 1. The signal is completely transferred when it
 110     has received for the first time the whole reversed signature.
 111
 112 CAVEATS
 113     This type of IPC is highly unreliable. Send little data at slow speed if
 114     you want it to reach its goal.
 115
 116     "SIGUSR{1,2}" seem to interrupt sleep, so it's not a good idea to
 117     transfer data to a sleeping process.
 118
 119 DEPENDENCIES
 120     Carp (standard since perl 5), POSIX (idem), Time::HiRes (since perl
 121     5.7.3) and utf8 (since perl 5.6) are required.
 122
 123 SEE ALSO
 124     perlipc for information about signals in perl.
 125
 126     For truly useful IPC, search for shared memory, pipes and semaphores.
 127
 128 AUTHOR
 129     Vincent Pit, "<perl at profvince.com>"
 130
 131     You can contact me by mail or on #perl @ FreeNode (Prof_Vince).
 132
 133 BUGS
 134     Please report any bugs or feature requests to "bug-ipc-morsesignals at
 135     rt.cpan.org", or through the web interface at
 136     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-MorseSignals>. I
 137     will be notified, and then you'll automatically be notified of progress
 138     on your bug as I make changes.
 139
 140 SUPPORT
 141     You can find documentation for this module with the perldoc command.
 142
 143         perldoc IPC::MorseSignals
 144
 145 ACKNOWLEDGEMENTS
 146     Thanks for the inspiration, mofino ! I hope this module will fill all
 147     your IPC needs. :)
 148
 149 COPYRIGHT & LICENSE
 150     Copyright 2007 Vincent Pit, all rights reserved.
 151
 152     This program is free software; you can redistribute it and/or modify it
 153     under the same terms as Perl itself.
 154