[ViewVC] Diff of: cvs/AnyEvent-Fork-RPC/README

Comparing AnyEvent-Fork-RPC/README (file contents):
Revision 1.4 by root, Wed Sep 25 11:06:11 2013 UTC vs.
Revision 1.5 by root, Thu May 12 16:54:43 2016 UTC

     child process may exit at any time, so you should call $done only when
     you really *are* done.
   Example 2: Asynchronous Backend
     This example implements multiple count-downs in the child, using
-    AnyEvent timers. While this is a bit silly (one could use timers in te
+    AnyEvent timers. While this is a bit silly (one could use timers in the
     parent just as well), it illustrates the ability to use AnyEvent in the
     child and the fact that responses can arrive in a different order then
     the requests.
     It also shows how to embed the actual child code into a "__DATA__"
             the synchronous backend.
             By overriding this you can prolong the life of a RPC process
             after e.g. the parent has exited by running the event loop in
             the provided function (or simply calling it, for example, when
-            your child process uses EV you could provide EV::loop as "done"
+            your child process uses EV you could provide EV::run as "done"
             function).
             Of course, in that case you are responsible for exiting at the
             appropriate time and not returning from
             to be transferred between the processes. For this, they have to
             be frozen and thawed in both parent and child processes.
             By default, only octet strings can be passed between the
             processes, which is reasonably fast and efficient and requires
-            no extra modules.
+            no extra modules (the "AnyEvent::Fork::RPC" distribution does
+            not provide these extra serialiser modules).
             For more complicated use cases, you can provide your own freeze
             and thaw functions, by specifying a string with perl source
             code. It's supposed to return two code references when
             evaluated: the first receives a list of perl values and must
             If you need an external module for serialisation, then you can
             either pre-load it into your AnyEvent::Fork process, or you can
             add a "use" or "require" statement into the serialiser string.
             Or both.
-            Here are some examples - some of them are also available as
+            Here are some examples - all of them are also available as
             global variables that make them easier to use.
-            octet strings - $AnyEvent::Fork::RPC::STRING_SERIALISER
+            $AnyEvent::Fork::RPC::STRING_SERIALISER - octet strings only
-                This serialiser concatenates length-prefixes octet strings,
+                This serialiser (currently the default) concatenates
-                and is the default. That means you can only pass (and
+                length-prefixes octet strings, and is the default. That
-                return) strings containing character codes 0-255.
+                means you can only pass (and return) strings containing
+                character codes 0-255.
+                The main advantages of this serialiser are the high speed
+                and that it doesn't need another module. The main
+                disadvantage is that you are very limited in what you can
+                pass - only octet strings.
                 Implementation:
                    (
                       sub { pack   "(w/a*)*", @_ },
                       sub { unpack "(w/a*)*", shift }
                    )
+            $AnyEvent::Fork::RPC::CBOR_XS_SERIALISER - uses CBOR::XS
+                This serialiser creates CBOR::XS arrays - you have to make
+                sure the CBOR::XS module is installed for this serialiser to
+                work. It can be beneficial for sharing when you preload the
+                CBOR::XS module in a template process.
+                CBOR::XS is about as fast as the octet string serialiser,
+                but supports complex data structures (similar to JSON) and
+                is faster than any of the other serialisers. If you have the
+                CBOR::XS module available, it's the best choice.
+                The encoder enables "allow_sharing" (so this serialisation
+                method can encode cyclic and self-referencing data
+                structures).
+                Implementation:
+                   use CBOR::XS ();
+                   (
+                      sub {    CBOR::XS::encode_cbor_sharing \@_ },
+                      sub { @{ CBOR::XS::decode_cbor shift } }
+                   )
-            json - $AnyEvent::Fork::RPC::JSON_SERIALISER
+            $AnyEvent::Fork::RPC::JSON_SERIALISER - uses JSON::XS or JSON
                 This serialiser creates JSON arrays - you have to make sure
                 the JSON module is installed for this serialiser to work. It
                 can be beneficial for sharing when you preload the JSON
                 module in a template process.
                    (
                       sub {    JSON::encode_json \@_ },
                       sub { @{ JSON::decode_json shift } }
                    )
-            storable - $AnyEvent::Fork::RPC::STORABLE_SERIALISER
+            $AnyEvent::Fork::RPC::STORABLE_SERIALISER - Storable
                 This serialiser uses Storable, which means it has high
                 chance of serialising just about anything you throw at it,
                 at the cost of having very high overhead per operation. It
                 also comes with perl. It should be used when you need to
                 serialise complex data structures.
                    (
                       sub {    Storable::freeze \@_ },
                       sub { @{ Storable::thaw shift } }
                    )
-            portable storable - $AnyEvent::Fork::RPC::NSTORABLE_SERIALISER
+            $AnyEvent::Fork::RPC::NSTORABLE_SERIALISER - portable Storable
                 This serialiser also uses Storable, but uses it's "network"
                 format to serialise data, which makes it possible to talk to
                 different perl binaries (for example, when talking to a
                 process created with AnyEvent::Fork::Remote).
     Asynchronous Backend
         For the asynchronous backend, things are more complicated: Whenever
         it listens for another request by the parent, it might detect that
         the socket was closed (e.g. because the parent exited). It will sotp
         listening for new requests and instead try to write out any
-        remaining data (if any) or simply check whether the socket cna be
+        remaining data (if any) or simply check whether the socket can be
         written to. After this, the RPC process is effectively done - no new
         requests are incoming, no outstanding request data can be written
         back.
         Since chances are high that there are event watchers that the RPC
         1000 jobs are queued and the jobs are slow, they will all run
         concurrently. The child must implement some queueing/limiting
         mechanism if this causes problems. Alternatively, the parent could
         limit the amount of rpc calls that are outstanding.
-        Blocking use of condvars is not supported.
+        Blocking use of condvars is not supported (in the main thread,
+        outside of e.g. Coro threads).
         Using event-based modules such as IO::AIO, Gtk2, Tk and so on is
         easy.
   Passing file descriptors
     so you might want to look into AnyEvent::FDpasser which can handle the
     gory details.
 EXCEPTIONS
     There are no provisions whatsoever for catching exceptions at this time
-    - in the child, exeptions might kill the process, causing calls to be
+    - in the child, exceptions might kill the process, causing calls to be
     lost and the parent encountering a fatal error. In the parent,
     exceptions in the result callback will not be caught and cause undefined
     behaviour.
 SEE ALSO

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-Fork-RPC/README (file contents): Revision 1.4 by root, Wed Sep 25 11:06:11 2013 UTC vs. Revision 1.5 by root, Thu May 12 16:54:43 2016 UTC

Diff Legend

Comparing AnyEvent-Fork-RPC/README (file contents):
Revision 1.4 by root, Wed Sep 25 11:06:11 2013 UTC vs.
Revision 1.5 by root, Thu May 12 16:54:43 2016 UTC