Copyright (C) 2022  Terence Kelly

=====================================================================

Changes  2022.08Aug.03.1659520468_Avon_7  ->  2022.10Oct.30.1667172241 (Avon 8)

Previous release ("Avon 7") was included in persistent memory gawk
(gawk 5.2) and thereby extensively tested on a wide range of hardware
and software platforms.  Testing turned up one genuine pma bug and
several portability/compatability issues; see the README file.

Re-wrote binary search in addrgap() function to fix unintended
wraparound of unsigned integer, which caused initialization to fail
on s390x-suse-linux, where mmap() succeeds for length values greater
than 2^63.  Thanks to Andreas Schwab for reporting this bug and
testing the fix.

Thanks also to gawk maintainer Arnold Robbins for preliminary tests
on several sub-species of BSD, which revealed two problems; see the
README file.  If you know about BSD and can spare time to look into
this, please contact me.

Hermann Peifer tested pm-gawk and identified several bugs.  Peifer
and Kevin O'Malley ran tests on MacOS/M1, discovering and confirming
that -no-pie is not obeyed on this platform.  Atul Prakash ran tests
on CIFS, and Corinna Vinschen ran tests on Cygwin.

= = = = = = = = = =

Future plans (not promises; subject to change):
* new interface to allow clients to msync heap file, possibly also
     snapshot as with gdbm
* new verbosity level 4:  TRC ("trace") for many current FYIs
* re-arrange integrity checking, expose in pma.h
* stand-alone heap integrity checker program
* enable assertions and/or integrity checks via envar
* backtrace within integrity checker, enable via envar
* alternative to get/set root:  return pointer to heap's root pointer

=====================================================================

Changes  2022.07Jul.19.1658299753_Avon_6  ->  2022.08Aug.03.1659520468_Avon_7

Only one relatively minor change:  Fix integrity check in pma_init to
avoid rare unwanted overheads when compiled in NDEBUG mode.

=====================================================================

Changes  2022.05May.01_Avon_5  ->  2022.07Jul.19.1658299753_Avon_6

This round of changes was largely motivated by persistent gawk.
Thanks to gawk maintainer Arnold Robbins and Corinna Vinschen for
helpful suggestions, to Nelson Beebe for access to machines for
testing, and to Haris Volos for conducting extensive correctness
and performance tests.

00_README:
* add notes on OS configuration and performance
* clarify 8-byte machine word requirement
* urge users to run tests with assertions enabled
* clarify (non-)portability of heap files
* update URLs to pma and pm-gawk publications
* add URLs for official gawk

pma.h: pma_init():
* encourage large sparse heap files
* clarify return value
* clarify rules & recommendations for persistent heap file
* integrity check may be slow

pma.c:
* accommodate older compilers that reject certain legal code (himask)
* modernize printf formats, e.g., "z" for size_t
* change some assertions to ERRs
* allow environment variable to over-ride pma_init verbosity
* enforce stricter alignment for memory mapping of heap file
* relax constraints on size of heap file

=====================================================================