------------------------------------------------------------------------------
--                                                                          --
--                         GNAT COMPILER COMPONENTS                         --
--                                                                          --
--        S Y S T E M . F I N A L I Z A T I O N _ P R I M I T I V E S       --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2023-2026, Free Software Foundation, Inc.          --
--                                                                          --
-- GNAT is free software;  you can  redistribute it  and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
-- GNAT was originally developed  by the GNAT team at  New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc.      --
--                                                                          --
------------------------------------------------------------------------------

with System.OS_Locks;
with System.Storage_Elements;

--  This package encapsulates the types and operations used by the compiler
--  to support finalization of objects of finalizable types (types derived
--  from standard Ada types Controlled and Limited_Controlled, as well as
--  types declared with the GNAT Finalizable aspect).

package System.Finalization_Primitives with Preelaborate is

   use type System.Storage_Elements.Storage_Offset;

   type Finalize_Address_Ptr is access procedure (Obj : System.Address);
   --  Values of this type denote finalization procedures associated with
   --  objects that have controlled parts. For convenience, such objects
   --  are simply referred to as controlled objects in the remainder of
   --  this package.

   type Master_Node is private;
   --  Each controlled object associated with a finalization master has an
   --  associated master node created by the compiler.

   type Master_Node_Ptr is access all Master_Node;
   for Master_Node_Ptr'Storage_Size use 0;
   --  A reference to a master node. Since this type may not be used to
   --  allocate objects, its storage size is zero.

   --------------------------------------------------------------------------
   --  Types and operations of finalization masters: A finalization master
   --  is used to manage a set of controlled objects declared at the library
   --  level of the program or associated with the declarative part of a
   --  subprogram or other closed scopes (block statements, for example).

   type Finalization_Master
     (Exceptions_OK : Boolean;
      Extra_Info    : Boolean;
      Library_Level : Boolean) is limited private;
   --  Objects of this type encapsulate an ordered list of zero or more master
   --  nodes, each of which is associated with a controlled object.

   procedure Attach_Object_To_Master
     (Object_Address   : System.Address;
      Finalize_Address : not null Finalize_Address_Ptr;
      Node             : not null Master_Node_Ptr;
      Master           : in out Finalization_Master);
   --  Associates a controlled object and its master node with a given master.
   --  Finalize_Address denotes the operation to be called to finalize the
   --  object (which could be a user-declared Finalize procedure or a procedure
   --  generated by the compiler). An object can be associated with at most one
   --  finalization master.

   procedure Attach_Object_To_Node
     (Object_Address   : System.Address;
      Finalize_Address : not null Finalize_Address_Ptr;
      Node             : in out Master_Node);
   --  Associates a controlled object with its master node only. This is used
   --  when there is a single object to be finalized in the context, as well as
   --  for objects that need special processing (return object in an extended
   --  return statement or transient objects).

   procedure Chain_Node_To_Master
     (Node   : not null Master_Node_Ptr;
      Master : in out Finalization_Master);
   --  Chain a master node to the given master. This is used to chain the node
   --  to the master of the enclosing scope for the objects that need special
   --  processing mentioned for Attach_Object_To_Node.

   procedure Finalize_Master (Master : in out Finalization_Master);
   --  Finalizes each of the controlled objects associated with Master, in the
   --  reverse of the order in which they were attached. Calls to the procedure
   --  with a Master that has already been finalized have no effects.

   procedure Finalize_Object
     (Node             : in out Master_Node;
      Finalize_Address : Finalize_Address_Ptr);
   --  Finalizes the controlled object attached to Node by generating a call to
   --  Finalize_Address on it, which has to be equal to Node.Finalize_Address.
   --  The weird redundancy is intended to help the optimizer turn an indirect
   --  call to Finalize_Address into a direct one and then inline it if needed,
   --  after having inlined Finalize_Object itself. Calls to the procedure with
   --  a Node that has already been finalized have no effects.

   procedure Suppress_Object_Finalize_At_End (Node : in out Master_Node);
   --  Changes the state of Node to effectively suppress a call to Node's
   --  associated object's Finalize procedure. This is called at the end
   --  of an extended return statement of a function whose result type
   --  needs finalization, to ensure that the function's return object is
   --  not finalized within the function in the case the return statement
   --  is completed normally (it will still be finalized if an exception
   --  is raised before the normal completion of the return statement).

   --------------------------------------------------------------------------
   --  Types and operations of finalization collections: A finalization
   --  collection is used to manage a set of controlled objects associated
   --  with an access type. Such collections are always associated with a
   --  finalization master, either at the library-level or within a subprogram,
   --  depending on where the access type is declared, and the collection
   --  object itself is managed via a Master_Node attached to its finalization
   --  master.

   type Finalization_Collection is limited private
     with Finalizable => (Initialize           => Initialize,
                          Finalize             => Finalize,
                          Relaxed_Finalization => Standard.False);
   --  Objects of this type encapsulate a set of zero or more controlled
   --  objects associated with an access type. The compiler ensures that
   --  each finalization collection is in turn associated with a finalization
   --  master.

   type Finalization_Collection_Ptr is access all Finalization_Collection;
   for Finalization_Collection_Ptr'Storage_Size use 0;
   --  A reference to a collection. Since this type may not be used to
   --  allocate objects, its storage size is zero.

   procedure Initialize (Collection : in out Finalization_Collection);
   --  Initializes the dummy head of a collection

   procedure Finalize (Collection : in out Finalization_Collection);
   --  Finalizes each object that has been associated with a finalization
   --  collection, in some arbitrary order. Calls to this procedure with
   --  a collection that has already been finalized have no effect.

   procedure Attach_Object_To_Collection
     (Object_Address   : System.Address;
      Finalize_Address : not null Finalize_Address_Ptr;
      Collection       : in out Finalization_Collection);
   --  Associates a controlled object allocated for some access type with a
   --  given finalization collection. Finalize_Address denotes the operation
   --  to be called to finalize the object (which could be a user-declared
   --  Finalize procedure or a procedure generated by the compiler). An object
   --  can be associated with at most one finalization collection.

   procedure Detach_Object_From_Collection (Object_Address : System.Address);
   --  Removes a controlled object from its associated finalization collection.
   --  Calls to the procedure with an object that has already been detached
   --  have no effects.

   function Header_Alignment return System.Storage_Elements.Storage_Count;
   --  Return the alignment of the header to be placed immediately in front of
   --  a controlled object allocated for some access type, in storage units.

   function Header_Size return System.Storage_Elements.Storage_Count;
  --  Return the size of the header to be placed immediately in front of a
  --  controlled object allocated for some access type, in storage units.

private

   --  Finalization masters:

   --  Master node type structure. Finalize_Address comes first because it is
   --  an access-to-subprogram and, therefore, might be twice as large and as
   --  aligned as an access-to-object on some platforms.

   type Master_Node is record
      Finalize_Address : Finalize_Address_Ptr := null;
      Object_Address   : System.Address       := Null_Address;
      Next             : Master_Node_Ptr      := null;
   end record;

    --  Finalization master type structure. A unique master is associated
    --  with each scope containing controlled objects.

   type Finalization_Master
     (Exceptions_OK : Boolean;
      Extra_Info    : Boolean;
      Library_Level : Boolean) is limited
   record
      Head : Master_Node_Ptr := null;
   end record;

   --  These operations need to be performed in line for maximum performance

   pragma Inline (Attach_Object_To_Master);
   pragma Inline (Attach_Object_To_Node);
   pragma Inline (Chain_Node_To_Master);
   pragma Inline (Finalize_Object);
   pragma Inline (Suppress_Object_Finalize_At_End);

   --  Finalization collections:

   type Collection_Node;
   --  Each controlled object associated with a finalization collection has
   --  an associated object of this type.

   type Collection_Node_Ptr is access all Collection_Node;
   for Collection_Node_Ptr'Storage_Size use 0;
   pragma No_Strict_Aliasing (Collection_Node_Ptr);
   --  A reference to a collection node. Since this type may not be used to
   --  allocate objects, its storage size is zero.

   --  Collection node type structure. Finalize_Address comes first because it
   --  is an access-to-subprogram and, therefore, might be twice as large and
   --  as aligned as an access-to-object on some platforms.

   type Collection_Node is record
      Finalize_Address : Finalize_Address_Ptr := null;
      --  A pointer to the Finalize_Address procedure of the object

      Enclosing_Collection : Finalization_Collection_Ptr := null;
      --  A pointer to the collection to which the node is attached

      Prev : Collection_Node_Ptr := null;
      Next : Collection_Node_Ptr := null;
      --  Collection nodes are managed as a circular doubly-linked list
   end record;

   function Header_Alignment return System.Storage_Elements.Storage_Count is
     (Collection_Node'Alignment);

   function Header_Size return System.Storage_Elements.Storage_Count is
     (Collection_Node'Object_Size / Storage_Unit);

   --  Finalization collection type structure

   type Finalization_Collection is limited record
      Head : aliased Collection_Node;
      --  The head of the circular doubly-linked list of collection nodes

      Lock : aliased System.OS_Locks.RTS_Lock;
      --  A lock to synchronize concurrent accesses to the collection

      Finalization_Started : Boolean;
      --  A flag used to detect allocations which occur during the finalization
      --  of a collection. The allocations must raise Program_Error. This may
      --  arise in a multitask environment.
   end record;

   --  This operation is very simple and thus can be performed in line

   pragma Inline (Initialize);

end System.Finalization_Primitives;