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-tasdeb.ads < prev    next >
Text File  |  2000-07-19  |  8KB  |  180 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                 GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS              --
  4. --                                                                          --
  5. --                  S Y S T E M . T A S K I N G . D E B U G                 --
  6. --                                                                          --
  7. --                                  S p e c                                 --
  8. --                                                                          --
  9. --                             $Revision: 1.16 $
  10. --                                                                          --
  11. --          Copyright (C) 1997-1998, Free Software Foundation, Inc.         --
  12. --                                                                          --
  13. -- GNARL 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. GNARL 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 GNARL; 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. -- GNARL was developed by the GNARL team at Florida State University. It is --
  32. -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
  33. -- State University (http://www.gnat.com).                                  --
  34. --                                                                          --
  35. ------------------------------------------------------------------------------
  36.  
  37. --  This package encapsulates all direct interfaces to task debugging services
  38. --  that are needed by gdb with gnat mode (1.17 and higher)
  39.  
  40. with Interfaces.C;
  41. with System.Tasking;
  42. with System.OS_Interface;
  43.  
  44. package System.Tasking.Debug is
  45.  
  46.    subtype int is Interfaces.C.int;
  47.    subtype unsigned_long is Interfaces.C.unsigned_long;
  48.  
  49.    package ST renames System.Tasking;
  50.  
  51.    Known_Tasks : array (0 .. 999) of Task_ID;
  52.    --  Global array of tasks read by gdb, and updated by
  53.    --  Create_Task and Finalize_TCB
  54.  
  55.    procedure Task_Creation_Hook (Thread : OS_Interface.Thread_Id);
  56.    --  This procedure is used to notify VxGdb of task's creation.
  57.    --  It must be called by the task's creator.
  58.  
  59.    procedure Task_Termination_Hook;
  60.    --  This procedure is used to notify VxGdb of task's termination.
  61.  
  62.    function Self return Task_ID;
  63.    --  return system ID of current task
  64.  
  65.    procedure List_Tasks;
  66.    --  Print a list of all the known Ada tasks with abbreviated state
  67.    --  information, one-per-line, to the standard output file
  68.  
  69.    procedure Print_Current_Task;
  70.    procedure Print_Task_Info_Header;
  71.    procedure Print_Task_Info (T : Task_ID);
  72.    --  Write TASK_ID of current task, in hexadecimal, as one line, to
  73.    --  the standard output file
  74.    --
  75.    --  Beware that Print_Current_Task may print garbage during an early
  76.    --  stage of activation. There is a small window where a task is just
  77.    --  initializing itself and has not yet recorded its own task Id.
  78.    --
  79.    --  Beware that Print_Current_Task will either not work at all or print
  80.    --  garbage if it has interrupted a thread of control that does not
  81.    --  correspond to any Ada task. For example, this is could happen if
  82.    --  the debugger interrupts a signal handler that is using an alternate
  83.    --  stack, or interrupts the dispatcher in the underlying thread
  84.    --  implementation.
  85.  
  86.    procedure Set_User_State (Value : Integer);
  87.  
  88.    procedure Print_Accept_Info (T : Task_ID);
  89.  
  90.    procedure Trace
  91.      (Self_ID  : Task_ID;
  92.       Msg      : String;
  93.       Other_ID : Task_ID;
  94.       Flag     : Character);
  95.  
  96.    procedure Trace
  97.      (Self_ID : Task_ID;
  98.       Msg     : String;
  99.       Flag    : Character);
  100.  
  101.    procedure Trace
  102.      (Msg  : String;
  103.       Flag : Character);
  104.  
  105.    procedure Trace
  106.      (Msg      : String;
  107.       Other_ID : Task_ID;
  108.       Flag     : Character);
  109.  
  110.    procedure Set_Trace
  111.      (Flag  : Character;
  112.       Value : Boolean := True);
  113.  
  114.    function Image (T : Task_ID) return String;
  115.  
  116.    procedure Suspend_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
  117.    --  Suspend all the tasks except the one whose associated thread is
  118.    --  Thread_Self by traversing All_Tasks_Lists and calling
  119.    --  System.Task_Primitives.Operations.Suspend_Task
  120.    --  Such functionnality is needed by gdb on some targets (e.g VxWorks)
  121.    --  Warning: for efficiency purposes, there is no locking.
  122.  
  123.    procedure Resume_All_Tasks (Thread_Self : OS_Interface.Thread_Id);
  124.    --  Resume all the tasks except the one whose associated thread is
  125.    --  Thread_Self by traversing All_Tasks_Lists and calling
  126.    --  System.Task_Primitives.Operations.Continue_Task
  127.    --  Such functionnality is needed by gdb on some targets (e.g VxWorks)
  128.    --  Warning: for efficiency purposes, there is no locking.
  129.  
  130. end System.Tasking.Debug;
  131.  
  132. -----------------------------
  133. -- Use of These Functions  --
  134. -----------------------------
  135.  
  136. --  Calling complicated functions from the debugger is generally pretty
  137. --  risky, especially in a multithreaded program.
  138.  
  139. --  The debugger may interrupt something that is not an Ada task,
  140. --  within the thread implementation, and which is not async-safe.
  141.  
  142. --  For example, under Solaris, it can interrupt code in "_dynamiclwps",
  143. --  which seems to serve as dispatcher when all the user threads are
  144. --  suspended. By experience, we have found that one cannot safely
  145. --  do certain things, apparently including calls to thread primitives
  146. --  from the debugger if the debugger has interrupted at one of these
  147. --  unsafe points. In general, if you interrupt a running program
  148. --  asynchronously (e.g. via control-C), it will not be safe to
  149. --  call the subprograms in this package.
  150.  
  151. -----------------
  152. -- Future work --
  153. -----------------
  154.  
  155. --  It would be nice to be able to tell whether execution has been
  156. --  interrupted in an Ada task. A heuristic way of checking this would
  157. --  be if we added to the Ada TCB a component that always contains a
  158. --  constant value that is unlikely to occur accidentally in code or
  159. --  data. We could then check this in the debugger-callable subprograms,
  160. --  and simply return an error code if it looks unsafe to proceed.
  161.  
  162. --  ???
  163. --  Recently we have added such a marker as a local variable of the
  164. --  task-wrapper routine. This allows Self to generate a fake ATCB for
  165. --  non-Ada threads of control. Given this capability, it is probably
  166. --  time to revisit the issue above.
  167.  
  168. --  DEADLOCK
  169.  
  170. --  We follow a simple rule here to avoid deadlock:
  171.  
  172. --  We do not use any locks in functions called by gdb, and we do not
  173. --  traverse linked lists.
  174. --
  175. --  The use of an array (Known_Tasks) has many advantages:
  176.  
  177. --   - Easy and fast to examine;
  178. --   - No risk of dangling references (to the next element) when traversing
  179. --     the array.
  180.