home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / adav313.zip / gnat-3_13p-os2-bin-20010916.zip / emx / gnatlib / s-shamem.ads < prev    next >
Text File  |  2000-07-19  |  10KB  |  191 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                         GNAT COMPILER COMPONENTS                         --
  4. --                                                                          --
  5. --                 S Y S T E M . S H A R E D _ M E M O R Y                  --
  6. --                                                                          --
  7. --                                 S p e c                                  --
  8. --                                                                          --
  9. --                            $Revision: 1.2 $                              --
  10. --                                                                          --
  11. --            Copyright (C) 1998, Free Software Foundation, Inc.            --
  12. --                                                                          --
  13. -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14. -- terms of the  GNU General Public License as published  by the Free Soft- --
  15. -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16. -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17. -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18. -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19. -- for  more details.  You should have  received  a copy of the GNU General --
  20. -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21. -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22. -- MA 02111-1307, USA.                                                      --
  23. --                                                                          --
  24. -- As a special exception,  if other files  instantiate  generics from this --
  25. -- unit, or you link  this unit with other files  to produce an executable, --
  26. -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27. -- covered  by the  GNU  General  Public  License.  This exception does not --
  28. -- however invalidate  any other reasons why  the executable file  might be --
  29. -- covered by the  GNU Public License.                                      --
  30. --                                                                          --
  31. -- GNAT was originally developed  by the GNAT team at  New York University. --
  32. -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
  33. --                                                                          --
  34. ------------------------------------------------------------------------------
  35.  
  36. --  This package manages the shared/persistant memory required for full
  37. --  implementation of variables in Shared_Passive packages, more precisely
  38. --  variables whose enclosing dynamic scope is a shared passive package.
  39.  
  40. --  -------------------------
  41. --  -- Shared Memory Model --
  42. --  -------------------------
  43.  
  44. --  The basic model used is that each partition that references the
  45. --  Shared_Passive package has a local copy of the package data that is
  46. --  initialized in accordance with the declarations of the package in
  47. --  the normal manner. The routines in System.Shared_Memory are then
  48. --  used to ensure that the values in these separate copies are properly
  49. --  synchronized with the state of the overall system.
  50.  
  51. --  This synchronization is ensured by maintaining a set of files in a
  52. --  designated directory. The directory is designated by setting the
  53. --  environment variable SHARED_MEMORY_DIRECTORY. This variable must be
  54. --  set for all partitions. If the environment variable is not defined,
  55. --  then the current directory is used.
  56.  
  57. --  There is one file for each variable. The name is the fully qualified
  58. --  name of the variable with all letters forced to lower case. For example,
  59. --  the variable Key_Name in the Shared_Passive package Shared_Data results
  60. --  in the file name shared_data.key_name.
  61.  
  62. --  If the file does not exist, it indicates that no partition has assigned
  63. --  a new value, so that the initial value is the correct one. This is the
  64. --  critical component of the model. It means that there is no system-wide
  65. --  synchronization required for initializing the package, since the shared
  66. --  memory files need not (and do not) reflect the initial state. There is
  67. --  therefore no issue of synchronizing initialization and read/write accress.
  68.  
  69. --  If the file does exist, it is a Stream_IO file that contains the most
  70. --  recently assigned value of the variable, as written by the use of the
  71. --  typ'Write stream attribute.
  72.  
  73. --  -----------------------
  74. --  -- Read/Write Access --
  75. --  -----------------------
  76.  
  77. --  The approach is as follows:
  78.  
  79. --    For each shared variable, var, an access routine varR is created whose
  80. --    body has the following form (this example is for Pkg.Var):
  81.  
  82. --      procedure varR is
  83. --         S : Ada.Streams.Stream_IO.Stream_Access;
  84. --      begin
  85. --         S := Shared_Mem_RFile ("pkg.var");
  86. --         if S /= null then
  87. --            typ'Read (S);
  88. --         end if;
  89. --      end varR;
  90.  
  91. --    The routine Shared_Mem_RFile in package System.Shared_Memory either
  92. --    returns null if the file does not exist, or otherwise a Stream_Access
  93. --    value that references the corresponding shared memory file, positioned
  94. --    at start of the file, ready to read the current value.
  95.  
  96. --    Each reference to the shared variable, var, is preceded by a call to
  97. --    the corresponding varR procedure, which either leaves the initial value
  98. --    unchanged if the file does not exist, or reads the current value from
  99. --    the shared memory file.
  100.  
  101. --    In addition, for each shared variable, var, an assignment routine
  102. --    is created whose body has the following form (again for Pgg.Var)
  103.  
  104. --      procedure VarA is
  105. --      begin
  106. --         typ'Write (Shared_Mem_WFile ("pkg.var"), var);
  107. --      end VarA;
  108.  
  109. --    The routine Shared_Mem_WFile is package System.Shared_Memory returns
  110. --    a Stream_Access value that references the corresponding shared memory
  111. --    file, positioned at the start, ready to write the new value.
  112.  
  113. --    Each assignment to the shared variable, var, is followed by a call
  114. --    to the corresponding varA procedure, which writes the new value to
  115. --    the shared memory file.
  116.  
  117. --  Note that there is no synchronization for these file read and write
  118. --  operations, since it is assumed that a correctly operating programs
  119. --  will provide appropriate synchronization. In particular, variables
  120. --  can be protected using protected types with no entries.
  121.  
  122. --  Note: a special circuit allows the use of stream attributes Read and
  123. --  Write for limited types (using the corresponding attribute for the
  124. --  full type), but there are limitations on the data that can be placed
  125. --  in shared passive partitions. See sem_smem.ads/adb for details.
  126.  
  127. --  ----------------------------------------------------------------
  128. --  -- Handling of Protected Objects in Shared Passive Partitions --
  129. --  ----------------------------------------------------------------
  130.  
  131. --  During the execution of a protected subprogram call, access is locked
  132. --  out using a global locking mechanism, as provided by the GNAT.Lock_Files
  133. --  capability. This package contains the lock and unlock calls, and the
  134. --  expander generates a call to the lock routine before the protected call
  135. --  and a call to the unlock routine after the protected call.
  136.  
  137. --  Within the code of the protected subprogram, the access to the protected
  138. --  object itself uses the local copy, without any special synchronization.
  139. --  Since global access is locked out, no other task or partition can attempt
  140. --  to read or write this data as long as the lock is held.
  141.  
  142. --  The data in the local copy does however need synchronizing with the
  143. --  global values in the shared memory file. This is achieved as follows:
  144.  
  145. --    The protected object generates a read and assignment routine as
  146. --    described for other shared passive variables. The code for the
  147. --    'Read and 'Write attributes (not normally allowed, but allowed
  148. --    in this special case) simply reads or writes the values of the
  149. --    components in the protected record.
  150.  
  151. --    The lock call is followed by a call to the shared read routine to
  152. --    synchronize the local copy to contain the proper global value.
  153.  
  154. --    The unlock call in the procedure case only is preceded by a call
  155. --    to the shared assign routine to synchronize the global shared
  156. --    memory files with the (possibly modified) local copy.
  157.  
  158. --  These calls to the read and assign routines, as well as the lock
  159. --  and unlock routines, are inserted by the expander (see exp_smem.adb).
  160.  
  161. with Ada.Streams.Stream_IO;
  162.  
  163. package System.Shared_Memory is
  164.  
  165.    package SIO renames Ada.Streams.Stream_IO;
  166.  
  167.    function Shared_Mem_RFile (Fname : String) return SIO.Stream_Access;
  168.    --  As described above, this routine returns null if the corresponding
  169.    --  shared memory file does not exist, and otherwise, if the file does
  170.    --  exist, a Stream_Access value that references the shared memory file,
  171.    --  positioned to the start, ready to read the current value.
  172.  
  173.    function Shared_Mem_WFile (Fname : String) return SIO.Stream_Access;
  174.    --  As described above, this routine returns a Stream_Access value that
  175.    --  references the shared memory file, positioned to the start, ready to
  176.    --  write the new value. The file is created by this call if it does not
  177.    --  already exist.
  178.  
  179.    procedure Shared_Mem_Lock;
  180.    --  This procedure claims the global shared memory lock. It is used for
  181.    --  protected types in shared passive packages. A call to this locking
  182.    --  routine is generated as the first operation in the code for the body
  183.    --  of a protected subprogram, and it busy waits if the lock is busy.
  184.  
  185.    procedure Shared_Mem_Unlock;
  186.    --  This procedure releases the lock obtaind by a prior call to the
  187.    --  Shared_Mem_Lock procedure, and is to be generated as the last
  188.    --  operation in the body of a protected subprogram.
  189.  
  190. end System.Shared_Memory;
  191.