Importing IPC-MorseSignals-0.05.tar.gz

[perl/modules/IPC-MorseSignals.git] / README

diff --git a/README b/README
index 0e5fb787c7941d2347025d6b89e716eaaba89981..b2925f0b79ceef9541351852cb7a7bc8fe2f2fc5 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     IPC::MorseSignals - Communicate between processes with Morse signals.
 
 VERSION
-    Version 0.02
+    Version 0.05
 
 SYNOPSIS
         use IPC::MorseSignals qw/msend mrecv/;
@@ -29,23 +29,28 @@ DESCRIPTION
 
 FUNCTIONS
   "msend"
-        msend $msg, $pid [, $speed ]
+        msend $msg, $pid [, speed => $speed, utf8 => $utf8 ]
 
     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 $pid is an array ref) at $speed bits per second. If the "utf8" flag
+    is set, the string will first be encoded in UTF-8. In this case, you
+    must turn it on for "mrecv" as well. Default speed is 512, don't set it
+    too low or the target will miss bits and the whole message will be
+    crippled. The "utf8" flag is turned off by default.
 
   "mrecv"
-        mrecv $callback
+        mrecv $callback [, utf => $utf8 ]
 
-    Takes as its sole argument the callback triggered when a complete
+    Takes as its first 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
+    "USR1" and "USR2" signal handlers. Basically, you want to use it like
     this :
 
         local @SIG{qw/USR1 USR2/} = mrecv sub { ... };
 
+    Turn on the utf8 flag if you know that the incoming strings are expected
+    to be in UTF-8. This flag is turned off by default.
+
 EXPORT
     This module exports on request its two only functions, "msend" and
     "mrecv".
@@ -53,12 +58,12 @@ EXPORT
 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 stream. The emitter
-    computes then the longuest sequence of successives 0 (say, "m") and 1
-    ("n"). A signature is then chosen :
+    into the same order as the characters occur in the string. The emitter
+    computes then the longuest sequence of successives 0 (say, m) and 1 (n).
+    A signature is then chosen :
 
-    If C(m > n), we take "n+1" times 1 follewed by 1 0 ;
-    Otherwise, we take "m+1" times 0 follewed by 1 1.
+    - 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 data bits
     and the reversed signature (i.e. the bits of the signature in the
@@ -72,17 +77,17 @@ 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.
+    "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 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>"