[M3commit] [modula3/cm3] e915d7: Make OrdSets utilize Pickle2's support of specials...

[GitHub]

  Branch: refs/heads/master
  Home:   https://github.com/modula3/cm3
  Commit: e915d7e17323df19afc576b91342f492e5931ff4
      https://github.com/modula3/cm3/commit/e915d7e17323df19afc576b91342f492e5931ff4
  Author: Rodney Bates <rodney.m.bates at acm.org>
  Date:   2016-08-16 (Tue, 16 Aug 2016)

  Changed paths:
    M m3-libs/ordsets/ordsets/README
    M m3-libs/ordsets/ordsets/src/OrdSets.ig
    M m3-libs/ordsets/ordsets/src/OrdSets.mg
    M m3-libs/ordsets/ordsets/src/Test.m3

  Log Message:
  -----------
  Make OrdSets utilize Pickle2's support of specials for pseudopointers.

Now there is as complete as possible support for pickling
pseudopointers, across machines of differing endianness and
word size.  Also various comment and test output fixes.

(* -------------------- Pseudopointers and Pickling ------------------------ *)

(* Pseudopointers are a space-saving internal representation trick.
   Since genuine pointer values are always aligned at least on an even
   boundary, odd values can be used to put certain small set values
   directly in a variable of type T, without the space and time
   overhead or the fragmentation of heap allocation.  OrdSets can
   use pseudopointers internally in this way to save space.  Its
   abstract behaviour is unchanged by their use.

   OrdSets will not construct pseudopointers unless client code has
   explicitly requested it to, by setting DoPseudopointers := TRUE.
   OrdSets will always correctly interpret in-memory pseudopointers.

   Pickling and unpickling of set values that are not pseudopointers
   always correctly adjusts for differences in endianness and word size
   (32 or 64 bit) between the pickle-writing and the pickle-reading
   system.

   The default mechanism of Pickles will treat any pseudopointers it
   encounters as having type INTEGER.  This will work correctly only
   if the word sizes are the same on the pickle-writing and the
   pickle-reading system.  Otherwise, the values will be garbled
   when unpickled.

   If client code requests, by calling RegisterPseudopointerPickleSpecial,
   on both the pickling and unpickling systems, pickling and unpickling
   of pseudopointer sets will be handled correctly for all mixes of word
   size and endianness.

   If, on the writing system, client code further requests, by setting
   DoPicklePseudopointers := TRUE, in-memory pseudopointers will be written
   as pseudopointers in the pickle file too, thus saving space there.
   Otherwise, they will be converted to normal internal representation
   in the pickle file.  Either way, they will be correctly unpickled, if
   client code has called RegisterPseudopointerPickleSpecial on the
   pickle-reading system.

   THERE ARE PITFALLS HERE:

   1) The general pickle mechanism can only handle registration of a
      single special for all pseudopointers in the entire link closure.

   2) Not registering the OrdSets pseudopointer special, and reading
      and writing pickles on systems with different word sizes will
      garble any in-memory pseudopointers.

   3) Registering the OrdSets pseudopointer special on one of the
      pickle-reading and pickle-writing systems, but not the other, will
      garble any in-memory pseudopointers.

*)