------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- This file is part of 'Cryostat', an Ada library for persistent storage.  --
--                                                                          --
-- (C) 2020 Stanislav Datskovskiy ( www.loper-os.org )                      --
-- http://wot.deedbot.org/17215D118B7239507FAFED98B98228A001ABFFC7.html     --
--                                                                          --
-- You do not have, nor can you ever acquire the right to use, copy or      --
-- distribute this software ; Should you use this software for any purpose, --
-- or copy and distribute it to anyone or in any manner, you are breaking   --
-- the laws of whatever soi-disant jurisdiction, and you promise to         --
-- continue doing so for the indefinite future. In any case, please         --
-- always : read and understand any software ; verify any PGP signatures    --
-- that you use - for any purpose.                                          --
------------------------------------------------------------------------------
------------------------------------------------------------------------------

------------------------------------------------------------------------------
"Cryostat" is a Fits-in-Head minimal library for adding persistent storage to
Ada data structures. It uses the MMap() system call, present in Linux (kernel
2.4 and newer) and all compatible operating systems.

Cryostat does NOT require enabling the use of pointerism, the secondary stack,
heap, or other bulky and objectionable GNAT features, in the calling program.
It does however require "finalization" to be enabled. This is used to
guarantee the safe sync-to-disk and closing of the backing MMap when the
data structure it contains goes out of scope.

See introductory article : http://www.loper-os.org/?p=3791
------------------------------------------------------------------------------

------------------------------------------------------------------------------
BUILD, TEST :
------------------------------------------------------------------------------

cd demo
gprbuild
./bin/cryodemo

Will produce this output :

T(0)    before :   0
T(Last) before :   0
T(0)    after  :   1
T(Last) after  :   1
OK.

On a second invocation :

T(0)    before :   1
T(Last) before :   1
T(0)    after  :   2
T(Last) after  :   2
OK.

... on the N-th invocation :

T(0)    before :   N-1
T(Last) before :   N-1
T(0)    after  :   N
T(Last) after  :   N
OK.

"cryotest.bin", the demo backing file, will consist of 512 megabytes of
byte value N, where N is the number of times the demo has executed.

E.g. after the first execution of "cryodemo" ,

$ hexdump -C cryotest.bin

00000000  01 01 01 01 01 01 01 01  01 01 01 01 01 01 01 01  |................|
*
20000000

------------------------------------------------------------------------------
TODO (as of version 633037) :
------------------------------------------------------------------------------

1) Add support for offsetted maps, and for maps which do not span the entire
   length of their backing file; likewise support runtime expansion of the
   backing file.

2) Currently, Cryostat is C-free. However, if added a .C for pulling constants
   from system headers, instead of the hardcoded MMap() flag values
   currently in unix.ads, could support architectures where non-standard values
   are used for these; in particular, MIPS32, MIPS64; and possibly others.
   See also: http://logs.nosuchlabs.com/log/trilema/2018-10-24#1865524

3) Add support for "anonymous" (i.e. not backed to disk storage) MMap, as a
   cleaner (when using large data structures) replacement for Ada's standard
   heap mechanism.

------------------------------------------------------------------------------