--- AnyEvent-Fork-RPC/RPC.pm	2013/11/20 16:17:22	1.35
+++ AnyEvent-Fork-RPC/RPC.pm	2016/05/12 16:53:13	1.38
@@ -465,7 +465,7 @@
 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 L<EV> you
-could provide L<EV::loop> as C<done> function).
+could provide L<EV::run> as C<done> function).
 
 Of course, in that case you are responsible for exiting at the appropriate
 time and not returning from
@@ -496,8 +496,10 @@
 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.
+By default, only octet strings can be passed between the processes,
+which is reasonably fast and efficient and requires no extra modules
+(the C<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
@@ -509,16 +511,20 @@
 pre-load it into your L<AnyEvent::Fork> process, or you can add a C<use>
 or C<require> statement into the serialiser string. Or both.
 
-Here are some examples - some of them are also available as global
+Here are some examples - all of them are also available as global
 variables that make them easier to use.
 
 =over 4
 
-=item octet strings - C<$AnyEvent::Fork::RPC::STRING_SERIALISER>
+=item C<$AnyEvent::Fork::RPC::STRING_SERIALISER> - octet strings only
 
-This serialiser concatenates length-prefixes octet strings, and is the
-default. That means you can only pass (and return) strings containing
-character codes 0-255.
+This serialiser (currently the default) concatenates length-prefixes octet
+strings, and is the default. That 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:
 
@@ -527,7 +533,7 @@
       sub { unpack "(w/a*)*", shift }
    )
 
-=item json - C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER>
+=item C<$AnyEvent::Fork::RPC::CBOR_XS_SERIALISER> - uses L<CBOR::XS>
 
 This serialiser creates CBOR::XS arrays - you have to make sure the
 L<CBOR::XS> module is installed for this serialiser to work. It can be
@@ -539,19 +545,18 @@
 other serialisers. If you have the L<CBOR::XS> module available, it's the
 best choice.
 
-Note that the CBOR::XS module supports some extensions to encode cyclic
-and self-referencing data structures, which are not enabled. You need to
-write your own serialiser to take advantage of these.
+The encoder enables C<allow_sharing> (so this serialisation method can
+encode cyclic and self-referencing data structures).
 
 Implementation:
 
    use CBOR::XS ();
    (
-      sub {    CBOR::XS::encode_cbor \@_ },
+      sub {    CBOR::XS::encode_cbor_sharing \@_ },
       sub { @{ CBOR::XS::decode_cbor shift } }
    )
 
-=item json - C<$AnyEvent::Fork::RPC::JSON_SERIALISER>
+=item C<$AnyEvent::Fork::RPC::JSON_SERIALISER> - uses L<JSON::XS> or L<JSON>
 
 This serialiser creates JSON arrays - you have to make sure the L<JSON>
 module is installed for this serialiser to work. It can be beneficial for
@@ -569,7 +574,7 @@
       sub { @{ JSON::decode_json shift } }
    )
 
-=item storable - C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER>
+=item C<$AnyEvent::Fork::RPC::STORABLE_SERIALISER> - L<Storable>
 
 This serialiser uses L<Storable>, which means it has high chance of
 serialising just about anything you throw at it, at the cost of having
@@ -584,7 +589,7 @@
       sub { @{ Storable::thaw shift } }
    )
 
-=item portable storable - C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER>
+=item C<$AnyEvent::Fork::RPC::NSTORABLE_SERIALISER> - portable Storable
 
 This serialiser also uses L<Storable>, but uses it's "network" format
 to serialise data, which makes it possible to talk to different
@@ -609,8 +614,8 @@
 =cut
 
 our $STRING_SERIALISER    = '(sub { pack "(w/a*)*", @_ }, sub { unpack "(w/a*)*", shift })';
-our $CBOR_XS_SERIALISER   = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
-our $JSON_SERIALISER      = 'use JSON     (); (sub { JSON::encode_json     \@_ }, sub { @{ JSON::decode_json     shift } })';
+our $CBOR_XS_SERIALISER   = 'use CBOR::XS (); (sub { CBOR::XS::encode_cbor_sharing \@_ }, sub { @{ CBOR::XS::decode_cbor shift } })';
+our $JSON_SERIALISER      = 'use JSON     (); (sub { JSON::encode_json             \@_ }, sub { @{ JSON::decode_json     shift } })';
 our $STORABLE_SERIALISER  = 'use Storable (); (sub { Storable::freeze  \@_ }, sub { @{ Storable::thaw shift } })';
 our $NSTORABLE_SERIALISER = 'use Storable (); (sub { Storable::nfreeze \@_ }, sub { @{ Storable::thaw shift } })';
 
@@ -894,7 +899,8 @@
 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. L<Coro> threads).
 
 Using event-based modules such as L<IO::AIO>, L<Gtk2>, L<Tk> and so on is
 easy.
@@ -970,7 +976,7 @@
 =head1 EXCEPTIONS
 
 There are no provisions whatsoever for catching exceptions at this time -
-in the child, exeptions might kill the process, causing calls to be lost
+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.