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-taspri.ads < prev    next >
Text File  |  1996-09-28  |  12KB  |  269 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                 GNU ADA RUNTIME LIBRARY (GNARL) COMPONENTS               --
  4. --                                                                          --
  5. --                S Y S T E M . T A S K _ P R I M I T I V E S               --
  6. --                                                                          --
  7. --                                  S p e c                                 --
  8. --                                                                          --
  9. --                             $Revision: 1.18 $                            --
  10. --                                                                          --
  11. --     Copyright (c) 1991,1992,1993,1994,1995 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 Interfaces.C;
  27. --  Used for Size_t;
  28.  
  29. with Interfaces.C.Pthreads;
  30. --  Used for, size_t,
  31. --            pthread_mutex_t,
  32. --            pthread_cond_t,
  33. --            pthread_t
  34.  
  35. with Interfaces.C.POSIX_RTE;
  36. --  Used for, Signal,
  37. --            siginfo_ptr,
  38.  
  39. with System.Task_Clock;
  40. --  Used for, Stimespec
  41.  
  42. with Unchecked_Conversion;
  43.  
  44. pragma Elaborate_All (Interfaces.C.Pthreads);
  45.  
  46. package System.Task_Primitives is
  47.  
  48.    --  Low level Task size and state definition
  49.  
  50.    type LL_Task_Procedure_Access is access procedure (Arg : System.Address);
  51.  
  52.    type Pre_Call_State is new System.Address;
  53.  
  54.    type Task_Storage_Size is new Interfaces.C.size_t;
  55.  
  56.    type Machine_Exceptions is new Interfaces.C.POSIX_RTE.Signal;
  57.  
  58.    type Error_Information is new Interfaces.C.POSIX_RTE.siginfo_ptr;
  59.  
  60. --   type Lock is new Interfaces.C.Pthreads.pthread_mutex_t;
  61. --   type Condition_Variable is new Interfaces.C.Pthreads.pthread_cond_t;
  62.  
  63. --  These definitions has to be private   ???
  64.    type Lock is private;
  65.    type Condition_Variable is private;
  66.  
  67.    --  The above types should both be limited. They are not due to a hack in
  68.    --  ATCB allocation which allocates a block of the correct size and then
  69.    --  assigns an initialized ATCB to it. This won't work with limited types.
  70.    --  When allocation is done with new, these can become limited once again.
  71.    --  ???
  72.  
  73.    type Task_Control_Block is record
  74.       LL_Entry_Point : LL_Task_Procedure_Access;
  75.       LL_Arg         : System.Address;
  76.       Thread         : Interfaces.C.Pthreads.pthread_t;
  77.       Stack_Size     : Task_Storage_Size;
  78.       Stack_Limit    : System.Address;
  79.    end record;
  80.  
  81.    type TCB_Ptr is access all Task_Control_Block;
  82.  
  83.    --  Task ATCB related and variables.
  84.  
  85.    function Address_To_TCB_Ptr is new
  86.      Unchecked_Conversion (System.Address, TCB_Ptr);
  87.  
  88.    procedure Initialize_LL_Tasks (T : TCB_Ptr);
  89.    --  Initialize GNULLI. T points to the Task Control Block that should
  90.    --  be initialized for use by the environment task.
  91.  
  92.    function Self return TCB_Ptr;
  93.    --  Return a pointer to the Task Control Block of the calling task.
  94.  
  95.    procedure Initialize_Lock (Prio : System.Priority; L : in out Lock);
  96.    --  Initialize a lock object. Prio is the ceiling priority associated
  97.    --  with the lock.
  98.  
  99.    procedure Finalize_Lock (L : in out Lock);
  100.    --  Finalize a lock object, freeing any resources allocated by the
  101.    --  corresponding Initialize_Lock.
  102.  
  103.    procedure Write_Lock (L : in out Lock; Ceiling_Violation : out Boolean);
  104.    --  Lock a lock object for write access to a critical section. After
  105.    --  this operation returns, the calling task owns the lock, and
  106.    --  no other Write_Lock or Read_Lock operation on the same object will
  107.    --  return the owner executes an Unlock operation on the same object.
  108.  
  109.    procedure Read_Lock (L : in out Lock; Ceiling_Violation : out Boolean);
  110.    --  Lock a lock object for read access to a critical section. After
  111.    --  this operation returns, the calling task owns the lock, and
  112.    --  no other Write_Lock operation on the same object will return until
  113.    --  the owner(s) execute Unlock operation(s) on the same object.
  114.    --  A Read_Lock to an owned lock object may return while the lock is
  115.    --  still owned, though an implementation may also implement
  116.    --  Read_Lock to have the same semantics.
  117.  
  118.    procedure Unlock (L : in out Lock);
  119.    --  Unlock a locked lock object. The results are undefined if the
  120.    --  calling task does not own the lock. Lock/Unlock operations must
  121.    --  be nested, that is, the argument to Unlock must be the object
  122.    --  most recently locked.
  123.  
  124.    procedure Initialize_Cond (Cond : in out Condition_Variable);
  125.    --  Initialize a condition variable object.
  126.  
  127.    procedure Finalize_Cond (Cond : in out Condition_Variable);
  128.    --  Finalize a condition variable object, recovering any resources
  129.    --  allocated for it by Initialize_Cond.
  130.  
  131.    procedure Cond_Wait (Cond : in out Condition_Variable; L : in out Lock);
  132.    --  Wait on a condition variable. The mutex object L is unlocked
  133.    --  atomically, such that another task that is able to lock the mutex
  134.    --  can be assured that the wait has actually commenced, and that
  135.    --  a Cond_Signal operation will cause the waiting task to become
  136.    --  eligible for execution once again. Before Cond_Wait returns,
  137.    --  the waiting task will again lock the mutex. The waiting task may become
  138.    --  eligible for execution at any time, but will become eligible for
  139.    --  execution when a Cond_Signal operation is performed on the
  140.    --  same condition variable object. The effect of more than one
  141.    --  task waiting on the same condition variable is unspecified.
  142.  
  143.    procedure Cond_Timed_Wait
  144.      (Cond      : in out Condition_Variable;
  145.       L         : in out Lock; Abs_Time : System.Task_Clock.Stimespec;
  146.       Timed_Out : out Boolean);
  147.    --  Wait on a condition variable, as for Cond_Wait, above. In addition,
  148.    --  the waiting task will become eligible for execution again
  149.    --  when the absolute time specified by Timed_Out arrives.
  150.  
  151.    procedure Cond_Signal (Cond : in out Condition_Variable);
  152.    --  Wake up a task waiting on the condition variable object specified
  153.    --  by Cond, making it eligible for execution once again.
  154.  
  155.    procedure Set_Priority (T : TCB_Ptr; Prio : System.Priority);
  156.    --  Set the priority of the task specified by T to P.
  157.  
  158.    procedure Set_Own_Priority (Prio : System.Priority);
  159.    --  Set the priority of the calling task to P.
  160.  
  161.    function Get_Priority (T : TCB_Ptr) return System.Priority;
  162.    --  Return the priority of the task specified by T.
  163.  
  164.    function Get_Own_Priority return System.Priority;
  165.    --  Return the priority of the calling task.
  166.  
  167.    procedure Create_LL_Task
  168.      (Priority       : System.Priority;
  169.       Stack_Size     :  Task_Storage_Size;
  170.       LL_Entry_Point : LL_Task_Procedure_Access;
  171.       Arg            : System.Address;
  172.       T              : TCB_Ptr);
  173.    --  Create a new low-level task with priority Priority. A new thread
  174.    --  of control is created with a stack size of at least Stack_Size,
  175.    --  and the procedure LL_Entry_Point is called with the argument Arg
  176.    --  from this new thread of control. The Task Control Block pointed
  177.    --  to by T is initialized to refer to this new task.
  178.  
  179.    procedure Exit_LL_Task;
  180.    --  Exit a low-level task. The resources allocated for the task
  181.    --  by Create_LL_Task are recovered. The task no longer executes, and
  182.    --  the effects of further operations on task are unspecified.
  183.  
  184.    procedure Abort_Task (T : TCB_Ptr);
  185.    --  Abort the task specified by T (the target task). This causes
  186.    --  the target task to asynchronously execute the handler procedure
  187.    --  installed by the target task using Install_Abort_Handler. The
  188.    --  effect of this operation is unspecified if there is no abort
  189.    --  handler procedure for the target task.
  190.  
  191.    procedure Test_Abort;
  192.    --  ??? Obsolete?  This is intended to allow implementation of
  193.    --      abortion and ATC in the absence of an asynchronous Abort_Task,
  194.    --      but I think that we decided that GNARL can handle this on
  195.    --      its own by making sure that there is an Undefer_Abortion at
  196.    --      every abortion synchronization point.
  197.  
  198.    type Abort_Handler_Pointer is access procedure (Context : Pre_Call_State);
  199.  
  200.    procedure Install_Abort_Handler (Handler : Abort_Handler_Pointer);
  201.    --  Install an abort handler procedure. This procedure is called
  202.    --  asynchronously by the calling task whenever a call to Abort_Task
  203.    --  specifies the calling task as the target. If the abort handler
  204.    --  procedure is asynchronously executed during a GNULLI operation
  205.    --  and then calls some other GNULLI operation, the effect is unspecified.
  206.  
  207.    procedure Install_Error_Handler (Handler : System.Address);
  208.    --  Install an error handler for the calling task. The handler will
  209.    --  be called synchronously if an error is encountered during the
  210.    --  execution of the calling task.
  211.  
  212.    procedure LL_Assert (B : Boolean; M : String);
  213.    --  If B is False, print the string M to the console and halt the
  214.    --  program.
  215.  
  216.    Task_Wrapper_Frame : constant Integer := 72;
  217.    --  This is the size of the frame for the Pthread_Wrapper procedure.
  218.  
  219.    type Proc is access procedure (Addr : System.Address);
  220.  
  221.  
  222.    --  Test and Set support
  223.    type TAS_Cell is private;
  224.    --  On some systems we can not assume that an arbitrary memory location
  225.    --  can be used in an atomic test and set instruction (e.g. on some
  226.    --  multiprocessor machines, only memory regions are cache interlocked).
  227.    --  TAS_Cell is private to facilitate adaption to a variety of
  228.    --  implementations.
  229.    procedure Initialize_TAS_Cell (Cell :    out TAS_Cell);
  230.    pragma Inline (Initialize_TAS_Cell);
  231.    --  Initialize a Test And Set Cell.  On some targets this will allocate
  232.    --  a system-level lock object from a special pool.  For most systems,
  233.    --  this is a nop.
  234.    procedure Finalize_TAS_Cell   (Cell : in out TAS_Cell);
  235.    pragma Inline (Finalize_TAS_Cell);
  236.    --  Finalize a Test and Set cell, freeing any resources allocated by the
  237.    --  corresponding Initialize_TAS_Cell.
  238.    procedure Clear        (Cell : in out TAS_Cell);
  239.    pragma Inline (Clear);
  240.    --  Set the state of the named TAS_Cell such that a subsequent call to
  241.    --  Is_Set will return False.  This operation must be atomic with
  242.    --  respect to the Is_Set and Test_And_Set operations for the same
  243.    --  cell.
  244.    procedure Test_And_Set (Cell : in out TAS_Cell; Result : out Boolean);
  245.    pragma Inline (Test_And_Set);
  246.    --  Modify the state of the named TAS_Cell such that a subsequent call
  247.    --  to Is_Set will return True.  Result is set to True if Is_Set
  248.    --  was False prior to the call, False otherwise.  This operation must
  249.    --  be atomic with respect to the Clear and Is_Set operations for the
  250.    --  same cell.
  251.    function  Is_Set       (Cell : in     TAS_Cell) return Boolean;
  252.    pragma Inline (Is_Set);
  253.    --  Returns the current value of the named TAS_Cell.  This operation
  254.    --  must be atomic with respect to the Clear and Test_And_Set operations
  255.    --  for the same cell.
  256. private
  257.  
  258.    type Lock is new Interfaces.C.Pthreads.pthread_mutex_t;
  259. --   type Condition_Variable is new Interfaces.C.Pthreads.pthread_cond_t;
  260.    type Condition_Variable is record
  261.       CV : Interfaces.C.Pthreads.pthread_cond_t;
  262.       Someone_Is_Waiting : Boolean;
  263.    end record;
  264.    type TAS_Cell is record
  265.       Value : aliased Boolean := False;
  266.    end record;
  267.  
  268. end System.Task_Primitives;
  269.