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

VERSION
    Version 0.07

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, 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
    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 %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 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
    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 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.

