README

   1 NAME
   2     IPC::MorseSignals - Communicate between processes with Morse signals.
   3
   4 VERSION
   5     Version 0.05
   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          local @SIG{qw/USR1 USR2/} = mrecv sub {
  15           print STDERR "received $_[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 ]
  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. If the "utf8" flag
  36     is set, the string will first be encoded in UTF-8. In this case, you
  37     must turn it on for "mrecv" as well. Default speed is 512, don't set it
  38     too low or the target will miss bits and the whole message will be
  39     crippled. The "utf8" flag is turned off by default.
  40
  41   "mrecv"
  42         mrecv $callback [, utf => $utf8 ]
  43
  44     Takes as its first argument the callback triggered when a complete
  45     message is received, and returns two code references that should replace
  46     "USR1" and "USR2" signal handlers. Basically, you want to use it like
  47     this :
  48
  49         local @SIG{qw/USR1 USR2/} = mrecv sub { ... };
  50
  51     Turn on the utf8 flag if you know that the incoming strings are expected
  52     to be in UTF-8. This flag is turned off by default.
  53
  54 EXPORT
  55     This module exports on request its two only functions, "msend" and
  56     "mrecv".
  57
  58 PROTOCOL
  59     Each byte of the data string is converted into its bits sequence, with
  60     bits of highest weight coming first. All those bits sequences are put
  61     into the same order as the characters occur in the string. The emitter
  62     computes then the longuest sequence of successives 0 (say, m) and 1 (n).
  63     A signature is then chosen :
  64
  65     - If m > n, we take n+1 times 1 follewed by one 0 ;
  66     - Otherwise, we take m+1 times 0 follewed by one 1.
  67
  68     The signal is then formed by concatenating the signature, the data bits
  69     and the reversed signature (i.e. the bits of the signature in the
  70     reverse order).
  71
  72     The receiver knows that the signature has been sent when it has catched
  73     at least one 0 and one 1. The signal is completely transferred when it
  74     has received for the first time the whole reversed signature.
  75
  76 CAVEATS
  77     This type of IPC is highly unreliable. Send little data at slow speed if
  78     you want it to reach its goal.
  79
  80     "SIGUSR{1,2}" seem to interrupt sleep, so it's not a good idea to
  81     transfer data to a sleeping process.
  82
  83 DEPENDENCIES
  84     Carp (standard since perl 5), POSIX (idem), Time::HiRes (since perl
  85     5.7.3) and utf8 (since perl 5.6) are required.
  86
  87 SEE ALSO
  88     perlipc for information about signals in perl.
  89
  90     For truly useful IPC, search for shared memory, pipes and semaphores.
  91
  92 AUTHOR
  93     Vincent Pit, "<perl at profvince.com>"
  94
  95     You can contact me by mail or on #perl @ FreeNode (Prof_Vince).
  96
  97 BUGS
  98     Please report any bugs or feature requests to "bug-ipc-morsesignals at
  99     rt.cpan.org", or through the web interface at
 100     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-MorseSignals>. I
 101     will be notified, and then you'll automatically be notified of progress
 102     on your bug as I make changes.
 103
 104 SUPPORT
 105     You can find documentation for this module with the perldoc command.
 106
 107         perldoc IPC::MorseSignals
 108
 109 ACKNOWLEDGEMENTS
 110     Thanks for the inspiration, mofino ! I hope this module will fill all
 111     your IPC needs. :)
 112
 113 COPYRIGHT & LICENSE
 114     Copyright 2007 Vincent Pit, all rights reserved.
 115
 116     This program is free software; you can redistribute it and/or modify it
 117     under the same terms as Perl itself.
 118