------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- 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.                                          --
------------------------------------------------------------------------------
------------------------------------------------------------------------------

with System;
with Ada.Finalization;
with Unix; use Unix;


package PMaps is
   
   pragma Preelaborate;
   
   -- Open file for map
   function OpenMapFile(Path     : in  String;
                        Writable : in  Boolean := False;
                        Create   : in  Boolean := False)
                       return FD
     with Pre => not ((not Writable) and Create);
   
   -- The address in memory where the map resides
   subtype MapAddress is System.Address;
   
   -- Internal representation of the map
   type PMap(Handle   : FD;      -- Unix FD handle of the open file
             Length   : Word;    -- The length (bytes) of the map
             Offset   : Word;    -- Offset into the file (normally zero)
             Create   : Boolean; -- Whether to create the file if not exists
             Writable : Boolean) -- Whether the map is writeable
      is new Ada.Finalization.Limited_Controlled with private;
   
   -- Test if map is usable
   function IsReady(Map : in PMap) return Boolean;
   
   -- Zero the entire map space
   procedure Zap(Map : in out PMap);
   
   -- Sync map to disk immediately
   procedure Sync(Map : in out PMap);
   
   -- Close map and mark it unusable
   procedure Stop(Map : in out PMap);
   
   -- Retrieve the address at which map resides
   function GetAddress(Map : in PMap) return MapAddress;
   
   -- Eggogs
   PMapFailedOpen  : exception; -- Could not open the given file
   PMapFailedMMap  : exception; -- Eggog when performed MMap()
   PMapFailedAddr  : exception; -- MMap() returned an unusable address
   PMapFailedSync  : exception; -- Sync failed
   PMapFailedUnmap : exception; -- Unmap failed
   PMapFailedClose : exception; -- Closing backing file failed
   PMapNotRunning  : exception; -- Tried to use an inactive map
   PMapNotWritable : exception; -- Tried to zap a read-only map
   
private
   
   -- Current state of the map
   type State is (Stop, Run, Eggog);
   
   type PMap(Handle   : FD;
             Length   : Word;
             Offset   : Word;
             Create   : Boolean;
             Writable : Boolean) is
     new Ada.Finalization.Limited_Controlled with 
      record
         -- Unix FD handle of the open file
         FileFD      : FD         := Handle;
         
         -- Whether to create the file if not exists
         MapCreate   : Boolean    := Create;
         
         -- Whether the map is writeable
         MapWritable : Boolean    := Writable;
         
         -- The length (bytes) of the map
         MapLength   : Word       := Length;
         
         -- Offset into the file (normally zero)
         MapOffset   : Word       := Offset;
         
         -- The address in memory where the map resides
         Address     : MapAddress := NullPtr;
         
         -- Current condition of this map
         Status      : State      := Stop;
      end record;
   
   -- Initialization
   overriding procedure Initialize(Map : in out PMap);
   
   -- Automatic sync and close of the map when leaving scope
   overriding procedure Finalize(Map : in out PMap);
   
end PMaps;