Use proto 1 pickles in ZEO/zrpc/Marshaller.encode().

This rehabilitates the good part of Andreas's change; adds
news; adds comments; and adds more comments about the
sequence of undocumented cPickle gimmicks this relies on.

NEWS.txt

@@ -2,6 +2,14 @@ What's new in ZODB3 3.3?
 ========================
 Release date: 17-Sep-2004
 
+ZEO
+---
+
+The encoding of RPC calls between server and client was being done
+with protocol 0 ("text mode") pickles, which could require sending
+four times as many bytes as necessary.  Protocol 1 pickles are used
+now.  Thanks to Andreas Jung for the diagnosis and cure.
+
 ZODB/component.xml
 ------------------
 

src/ZEO/zrpc/marshal.py

@@ -25,8 +25,20 @@ class Marshaller:
     def encode(self, msgid, flags, name, args):
         """Returns an encoded message"""
         # (We used to have a global pickler, but that's not thread-safe. :-( )
-        pickler = cPickle.Pickler()
+        # Note that args may contain very large binary pickles already; for
+        # this reason, it's important to use proto 1 (or higher) pickles here
+        # too.  For a long time, this used proto 0 pickles, and that can
+        # bloat our pickle to 4x the size (due to high-bit and control bytes
+        # being represented by \xij escapes in proto 0).
+        # Undocumented:  cPickle.Pickler accepts a lone protocol argument;
+        # pickle.py does not.
+        pickler = cPickle.Pickler(1)
         pickler.fast = 1
+
+        # Undocumented:  pickler.dump(), for a cPickle.Pickler, takes
+        # an optional boolean argument.  When true, it returns the pickle;
+        # when false or unspecified, it returns the pickler object itself.
+        # pickle.py does none of this.
         return pickler.dump((msgid, flags, name, args), 1)
 
     def decode(self, msg):