+++ /dev/null
-------------------------------------------------------------------------------
--- --
--- GNAT COMPILER COMPONENTS --
--- --
--- S Y S T E M . S H A R E D _ S T O R A G E --
--- --
--- S p e c --
--- --
--- $Revision: 1.2.10.2 $
--- --
--- Copyright (C) 1998-2001 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 2, 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. See the GNU General Public License --
--- for more details. You should have received a copy of the GNU General --
--- Public License distributed with GNAT; see file COPYING. If not, write --
--- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
--- MA 02111-1307, USA. --
--- --
--- As a special exception, if other files instantiate generics from this --
--- unit, or you link this unit with other files to produce an executable, --
--- this unit does not by itself cause the resulting executable to be --
--- covered by the GNU General Public License. This exception does not --
--- however invalidate any other reasons why the executable file might be --
--- covered by the GNU Public License. --
--- --
--- GNAT was originally developed by the GNAT team at New York University. --
--- Extensive contributions were provided by Ada Core Technologies Inc. --
--- --
-------------------------------------------------------------------------------
-
--- This package manages the shared/persistent storage required for
--- full implementation of variables in Shared_Passive packages, more
--- precisely variables whose enclosing dynamic scope is a shared
--- passive package. This implementation is specific to GNAT and GLADE
--- provides a more general implementation not dedicated to file
--- storage.
-
--- --------------------------
--- -- Shared Storage Model --
--- --------------------------
-
--- The basic model used is that each partition that references the
--- Shared_Passive package has a local copy of the package data that
--- is initialized in accordance with the declarations of the package
--- in the normal manner. The routines in System.Shared_Storage are
--- then used to ensure that the values in these separate copies are
--- properly synchronized with the state of the overall system.
-
--- In the GNAT implementation, this synchronization is ensured by
--- maintaining a set of files, in a designated directory. The
--- directory is designated by setting the environment variable
--- SHARED_MEMORY_DIRECTORY. This variable must be set for all
--- partitions. If the environment variable is not defined, then the
--- current directory is used.
-
--- There is one storage for each variable. The name is the fully
--- qualified name of the variable with all letters forced to lower
--- case. For example, the variable Var in the shared passive package
--- Pkg results in the storage name pkg.var.
-
--- If the storage does not exist, it indicates that no partition has
--- assigned a new value, so that the initial value is the correct
--- one. This is the critical component of the model. It means that
--- there is no system-wide synchronization required for initializing
--- the package, since the shared storages need not (and do not)
--- reflect the initial state. There is therefore no issue of
--- synchronizing initialization and read/write access.
-
--- -----------------------
--- -- Read/Write Access --
--- -----------------------
-
--- The approach is as follows:
-
--- For each shared variable, var, an access routine varR is created whose
--- body has the following form (this example is for Pkg.Var):
-
--- procedure varR is
--- S : Ada.Streams.Stream_IO.Stream_Access;
--- begin
--- S := Shared_Var_ROpen ("pkg.var");
--- if S /= null then
--- typ'Read (S);
--- Shared_Var_Close (S);
--- end if;
--- end varR;
-
--- The routine Shared_Var_ROpen in package System.Shared_Storage
--- either returns null if the storage does not exist, or otherwise a
--- Stream_Access value that references the corresponding shared
--- storage, ready to read the current value.
-
--- Each reference to the shared variable, var, is preceded by a
--- call to the corresponding varR procedure, which either leaves the
--- initial value unchanged if the storage does not exist, or reads
--- the current value from the shared storage.
-
--- In addition, for each shared variable, var, an assignment routine
--- is created whose body has the following form (again for Pkg.Var)
-
--- procedure VarA is
--- S : Ada.Streams.Stream_IO.Stream_Access;
--- begin
--- S := Shared_Var_WOpen ("pkg.var");
--- typ'Write (S, var);
--- Shared_Var_Close (S);
--- end VarA;
-
--- The routine Shared_Var_WOpen in package System.Shared_Storage
--- returns a Stream_Access value that references the corresponding
--- shared storage, ready to write the new value.
-
--- Each assignment to the shared variable, var, is followed by a call
--- to the corresponding varA procedure, which writes the new value to
--- the shared storage.
-
--- Note that there is no general synchronization for these storage
--- read and write operations, since it is assumed that a correctly
--- operating programs will provide appropriate synchronization. In
--- particular, variables can be protected using protected types with
--- no entries.
-
--- The routine Shared_Var_Close is called to indicate the end of a
--- read/write operations. This can be useful even in the context of
--- the GNAT implementation. For instance, when a read operation and a
--- write operation occur at the same time on the same partition, as
--- the same stream is used simultaneously, both operations can
--- terminate abruptly by raising exception Mode_Error because the
--- stream has been opened in read mode and then in write mode and at
--- least used by the read opartion. To avoid this unexpected
--- behaviour, we introduce a synchronization at the partition level.
-
--- Note: a special circuit allows the use of stream attributes Read and
--- Write for limited types (using the corresponding attribute for the
--- full type), but there are limitations on the data that can be placed
--- in shared passive partitions. See sem_smem.ads/adb for details.
-
--- ----------------------------------------------------------------
--- -- Handling of Protected Objects in Shared Passive Partitions --
--- ----------------------------------------------------------------
-
--- In the context of GNAT, during the execution of a protected
--- subprogram call, access is locked out using a locking mechanism
--- per protected object, as provided by the GNAT.Lock_Files
--- capability in the specific case of GNAT. This package contains the
--- lock and unlock calls, and the expander generates a call to the
--- lock routine before the protected call and a call to the unlock
--- routine after the protected call.
-
--- Within the code of the protected subprogram, the access to the
--- protected object itself uses the local copy, without any special
--- synchronization. Since global access is locked out, no other task
--- or partition can attempt to read or write this data as long as the
--- lock is held.
-
--- The data in the local copy does however need synchronizing with
--- the global values in the shared storage. This is achieved as
--- follows:
-
--- The protected object generates a read and assignment routine as
--- described for other shared passive variables. The code for the
--- 'Read and 'Write attributes (not normally allowed, but allowed
--- in this special case) simply reads or writes the values of the
--- components in the protected record.
-
--- The lock call is followed by a call to the shared read routine to
--- synchronize the local copy to contain the proper global value.
-
--- The unlock call in the procedure case only is preceded by a call
--- to the shared assign routine to synchronize the global shared
--- storages with the (possibly modified) local copy.
-
--- These calls to the read and assign routines, as well as the lock
--- and unlock routines, are inserted by the expander (see exp_smem.adb).
-
-with Ada.Streams.Stream_IO;
-
-package System.Shared_Storage is
-
- package SIO renames Ada.Streams.Stream_IO;
-
- function Shared_Var_ROpen (Var : String) return SIO.Stream_Access;
- -- As described above, this routine returns null if the
- -- corresponding shared storage does not exist, and otherwise, if
- -- the storage does exist, a Stream_Access value that references
- -- the shared storage, ready to read the current value.
-
- function Shared_Var_WOpen (Var : String) return SIO.Stream_Access;
- -- As described above, this routine returns a Stream_Access value
- -- that references the shared storage, ready to write the new
- -- value. The storage is created by this call if it does not
- -- already exist.
-
- procedure Shared_Var_Close (Var : in SIO.Stream_Access);
- -- This routine signals the end of a read/assign operation. It can
- -- be useful to embrace a read/write operation between a call to
- -- open and a call to close which protect the whole operation.
- -- Otherwise, two simultaneous operations can result in the
- -- raising of exception Data_Error by setting the access mode of
- -- the variable in an incorrect mode.
-
- procedure Shared_Var_Lock (Var : String);
- -- This procedure claims the shared storage lock. It is used for
- -- protected types in shared passive packages. A call to this
- -- locking routine is generated as the first operation in the code
- -- for the body of a protected subprogram, and it busy waits if
- -- the lock is busy.
-
- procedure Shared_Var_Unlock (Var : String);
- -- This procedure releases the shared storage lock obtaind by a
- -- prior call to the Shared_Mem_Lock procedure, and is to be
- -- generated as the last operation in the body of a protected
- -- subprogram.
-
-end System.Shared_Storage;
projects / msp430-gcc.git / blobdiff