home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / gnat-2.06-src.tgz / tar.out / fsf / gnat / ada / s-taprob.ads < prev    next >
Text File  |  1996-09-28  |  8KB  |  156 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                 GNU ADA RUNTIME LIBRARY (GNARL) COMPONENTS               --
  4. --                                                                          --
  5. --      S Y S T E M . T A S K I N G . P R O T E C T E D _ O B J E C T S     --
  6. --                                                                          --
  7. --                                  S p e c                                 --
  8. --                                                                          --
  9. --                             $Revision: 1.15 $                             --
  10. --                                                                          --
  11. --       Copyright (c) 1991,1992,1993,1994, FSU, All Rights Reserved        --
  12. --                                                                          --
  13. -- GNARL is free software; you can redistribute it  and/or modify it  under --
  14. -- terms  of  the  GNU  Library General Public License  as published by the --
  15. -- Free Software  Foundation;  either version 2, or (at  your  option)  any --
  16. -- later  version.  GNARL is distributed  in the hope that  it will be use- --
  17. -- ful, but but WITHOUT ANY WARRANTY;  without even the implied warranty of --
  18. -- MERCHANTABILITY  or  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Gen- --
  19. -- eral Library Public License  for more details.  You should have received --
  20. -- a  copy of the GNU Library General Public License along with GNARL;  see --
  21. -- file COPYING.LIB.  If not,  write to the  Free Software Foundation,  675 --
  22. -- Mass Ave, Cambridge, MA 02139, USA.                                      --
  23. --                                                                          --
  24. ------------------------------------------------------------------------------
  25.  
  26. with System.Compiler_Exceptions;
  27. --  Used for, Exception_ID
  28.  
  29. package System.Tasking.Protected_Objects is
  30.    --  This interface is described in the document
  31.    --  Gnu Ada Runtime Library Interface (GNARLI).
  32.  
  33.    pragma Elaborate_Body (System.Tasking.Protected_Objects);
  34.  
  35.    procedure Initialize_Protection
  36.      (Object            : access Protection;
  37.       Ceiling_Priority  : Integer;
  38.       Compiler_Info     : System.Address;
  39.       Entry_Bodies      : access Protected_Entry_Body_Array);
  40.    --  Initialize the Object parameter so that it can be used by the runtime
  41.    --  to keep track of the runtime state of a protected object.
  42.  
  43.    procedure Lock (Object : access Protection);
  44.    --  Lock a protected object for write access.  Upon return, the caller
  45.    --  owns the lock to this object, and no other call to Lock or
  46.    --  Lock_Read_Only with the same argument will return until the
  47.    --  corresponding call to Unlock has been made by the caller.
  48.  
  49.    procedure Lock_Read_Only (Object : access Protection);
  50.    --  Lock a protected object for read access.  Upon return, the caller
  51.    --  owns the lock for read access, and no other calls to Lock
  52.    --  with the same argument will return until the corresponding call
  53.    --  to Unlock has been made by the caller.  Other cals to Lock_Read_Only
  54.    --  may (but need not) return before the call to Unlock, and the
  55.    --  corresponding callers will also own the lock for read access.
  56.  
  57.    procedure Unlock (Object : access Protection);
  58.    --  Relinquish ownership of the lock for the object represented by
  59.    --  the Object parameter.  If this ownership was for write access, or
  60.    --  if it was for read access where there are no other read access
  61.    --  locks outstanding, one (or more, in the case of Lock_Read_Only)
  62.    --  of the tasks waiting on this lock (if any) will be given the
  63.    --  lock and allowed to return from the Lock or Lock_Read_Only call.
  64.  
  65.    procedure Protected_Entry_Call
  66.      (Object    : access Protection;
  67.       E         : Protected_Entry_Index;
  68.       Uninterpreted_Data : System.Address;
  69.       Mode      : Call_Modes;
  70.       Block     : out Communication_Block);
  71.    --  Make a protected entry call to the specified object.
  72.    --  Pend a protected entry call on the protected object represented
  73.    --  by Object.  A pended call is not queued; it may be executed immediately
  74.    --  or queued, depending on the state of the entry barrier.
  75.    --  E---The index representing the entry to be called.
  76.    --  Uninterpreted_Data---This will be returned by Next_Entry_Call
  77.    --   when this call is serviced.  It can be used by the compiler
  78.    --   to pass information between the caller and the server, in particular
  79.    --   entry parameters.
  80.    --  Mode---The kind of call to be pended.
  81.    --  Block---Information passed between one runtime call and another
  82.    --   by the compiler.
  83.  
  84.    procedure Service_Entries (Object : access Protection);
  85.    --  Service all entry queues of the specified object, executing the
  86.    --  corresponding bodies of any queued entry calls that are waiting
  87.    --  on True barriers.  This is used when the state of a protected
  88.    --  object may have changed, in particular after the execution of
  89.    --  the statement sequence of a protected procedure.
  90.    --  Note that servicing an entry may change the value of one or more
  91.    --  barriers, so this this routine keeps checking barriers until all of
  92.    --  them are closed.
  93.    --  This must be called with abortion deferred and with the corresponding
  94.    --  object locked.
  95.  
  96.    pragma Inline (Service_Entries);
  97.    --  !!! To try to be fairer to the callback interface.
  98.  
  99.    procedure Cancel_Protected_Entry_Call (Block : in out Communication_Block);
  100.    --  Attempt to cancel the most recent protected entry call.  If the call is
  101.    --  not queued abortably, wait until it is or until it has completed.
  102.    --  If the call is actually cancelled, the called object will be
  103.    --  locked on return from this call. Get_Cancelled (Block) can be
  104.    --  used to determine if the cancellation took place; there
  105.    --  may be entries needing service in this case.
  106.    --  Block passes information between this and other runtime calls.
  107.  
  108.    procedure Complete_Entry_Body (Object : access Protection);
  109.    --  Called from within an entry body procedure, indicates that the
  110.    --  corresponding entry call has been serviced.
  111.  
  112.    procedure Exceptional_Complete_Entry_Body
  113.      (Object : access Protection;
  114.       Ex     : System.Compiler_Exceptions.Exception_ID);
  115.    --  Perform all of the functions of Complete_Entry_Body.  In addition,
  116.    --  report in Ex the exception whose propagation terminated the entry
  117.    --  body to the runtime system.
  118.  
  119.    function Enqueued (Block : Communication_Block) return Boolean;
  120.    --  Returns True if the Protected_Entry_Call which returned the
  121.    --  specified Block object was queued; False otherwise.
  122.  
  123.    function Cancelled (Block : Communication_Block) return Boolean;
  124.    --  Returns True if the Protected_Entry_Call which returned the
  125.    --  specified Block object was cancelled, False otherwise.
  126.  
  127.    procedure Requeue_Protected_Entry
  128.      (Object     : access Protection;
  129.       New_Object : access Protection;
  130.       E          : Protected_Entry_Index;
  131.       With_Abort : Boolean);
  132.    --  If Object = New_Object, queue the protected entry call on Object
  133.    --   currently being serviced on the queue corresponding to the entry
  134.    --   represented by E.
  135.    --  If Object /= New_Object, transfer the call to New_Object.E,
  136.    --   executing or queuing it as appropriate.
  137.    --  With_Abort---True if the call is to be queued abortably, false
  138.    --   otherwise.
  139.  
  140.    procedure Requeue_Task_To_Protected_Entry
  141.      (New_Object : access Protection;
  142.       E          : Protected_Entry_Index;
  143.       With_Abort : Boolean);
  144.    --  Transfer task entry call currently being serviced to entry E
  145.    --   on New_Object.
  146.    --  With_Abort---True if the call is to be queued abortably, false
  147.    --   otherwise.
  148.  
  149.    function Protected_Count
  150.      (Object : Protection;
  151.       E      : Protected_Entry_Index)
  152.       return   Natural;
  153.    --  Return the number of entry calls to E on Object.
  154.  
  155. end System.Tasking.Protected_Objects;
  156.