[multiple changes]

2010-09-10  Bob Duff  <duff@adacore.com>

	* s-os_lib.ads, g-expect.ads: Add comments.

2010-09-10  Robert Dewar  <dewar@adacore.com>

	* exp_ch5.adb: Minor reformatting.

From-SVN: r164189

4 files changed, 97 insertions, 17 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index ceac7ff..62087b4 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,11 @@
+2010-09-10  Bob Duff  <duff@adacore.com>
+
+	* s-os_lib.ads, g-expect.ads: Add comments.
+
+2010-09-10  Robert Dewar  <dewar@adacore.com>
+
+	* exp_ch5.adb: Minor reformatting.
+
 2010-09-10  Thomas Quinot  <quinot@adacore.com>
 
 	* scos.ads: Add comments.
diff --git a/gcc/ada/exp_ch5.adb b/gcc/ada/exp_ch5.adb
index 089987b..8760cb7 100644
--- a/gcc/ada/exp_ch5.adb
+++ b/gcc/ada/exp_ch5.adb
@@ -1010,14 +1010,7 @@ package body Exp_Ch5 is
       function Build_Step (J : Nat) return Node_Id;
       --  The increment step for the index of the right-hand side is written
       --  as an attribute reference (Succ or Pred). This function returns
-      --  the corresponding node, which is placed at the end of theloop body.
-
-      --  Note that on the last iteration of the loop, the index is increased
-      --  (or decreased) past the corresponding bound. This is consistent with
-      --  the C semantics of the back-end, where such an off-by-one value on a
-      --  dead index variable is OK.  However, in CodePeer mode this leads to
-      --  spurious warnings, and thus we place a guard around the attribute
-      --  reference. For obvious reasons we only do this for CodePeer.
+      --  the corresponding node, which is placed at the end of the loop body.
 
       ----------------
       -- Build_Step --
@@ -1045,6 +1038,13 @@ package body Exp_Ch5 is
                    Expressions => New_List (
                      New_Occurrence_Of (Rnn (J), Loc))));
 
+      --  Note that on the last iteration of the loop, the index is increased
+      --  (or decreased) past the corresponding bound. This is consistent with
+      --  the C semantics of the back-end, where such an off-by-one value on a
+      --  dead index variable is OK.  However, in CodePeer mode this leads to
+      --  spurious warnings, and thus we place a guard around the attribute
+      --  reference. For obvious reasons we only do this for CodePeer.
+
          if CodePeer_Mode then
             Step :=
               Make_If_Statement (Loc,
diff --git a/gcc/ada/g-expect.ads b/gcc/ada/g-expect.ads
index 9a00cf0..18cf995 100644
--- a/gcc/ada/g-expect.ads
+++ b/gcc/ada/g-expect.ads
@@ -184,6 +184,9 @@ package GNAT.Expect is
    --  subprograms to also match on output on standard error.
    --
    --  Invalid_Process is raised if the process could not be spawned.
+   --
+   --  For information about spawning processes from tasking programs, see the
+   --  "NOTE: Spawn in tasking programs" in System.OS_Lib (s-os_lib.ads).
 
    procedure Close (Descriptor : in out Process_Descriptor);
    --  Terminate the process and close the pipes to it. It implicitly does the
diff --git a/gcc/ada/s-os_lib.ads b/gcc/ada/s-os_lib.ads
index 3b29ca9..a6418de 100755
--- a/gcc/ada/s-os_lib.ads
+++ b/gcc/ada/s-os_lib.ads
@@ -688,9 +688,8 @@ package System.OS_Lib is
    --  (notably Unix systems) a simple file name may also work (if the
    --  executable can be located in the path).
    --
-   --  "Spawn" should be avoided in tasking applications, since there are
-   --  subtle interactions between creating a process and signals/locks
-   --  that can cause troubles.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
    --
    --  Note: Arguments in Args that contain spaces and/or quotes such as
    --  "--GCC=gcc -v" or "--GCC=""gcc -v""" are not portable across all
@@ -717,7 +716,8 @@ package System.OS_Lib is
    --  by the operating system, or -1 under VxWorks and any other similar
    --  operating systems which have no notion of separately spawnable programs.
    --
-   --  "Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
 
    procedure Spawn
      (Program_Name           : String;
@@ -730,7 +730,8 @@ package System.OS_Lib is
    --  Standard Error output is also redirected.
    --  Return_Code is set to the status code returned by the operating system
    --
-   --  "Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
 
    procedure Spawn
      (Program_Name : String;
@@ -747,7 +748,8 @@ package System.OS_Lib is
    --  will be set to the status code returned by the operating system.
    --  Otherwise, Return_Code is undefined.
    --
-   --  "Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
 
    type Process_Id is private;
    --  A private type used to identify a process activated by the following
@@ -768,7 +770,8 @@ package System.OS_Lib is
    --  returned. Parameters are to be used as in Spawn. If Invalid_Pid is
    --  returned the program could not be spawned.
    --
-   --  "Non_Blocking_Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
    --
    --  This function will always return Invalid_Pid under VxWorks, since there
    --  is no notion of executables under this OS.
@@ -783,7 +786,8 @@ package System.OS_Lib is
    --  Standard Error output is also redirected. Invalid_Pid is returned
    --  if the program could not be spawned successfully.
    --
-   --  "Non_Blocking_Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
    --
    --  This function will always return Invalid_Pid under VxWorks, since there
    --  is no notion of executables under this OS.
@@ -801,7 +805,8 @@ package System.OS_Lib is
    --  file could not be created or if the program could not be spawned
    --  successfully.
    --
-   --  "Non_Blocking_Spawn" should not be used in tasking applications.
+   --  Spawning processes from tasking programs is not recommended. See
+   --  "NOTE: Spawn in tasking programs" below.
    --
    --  This function will always return Invalid_Pid under VxWorks, since there
    --  is no notion of executables under this OS.
@@ -827,6 +832,70 @@ package System.OS_Lib is
    --  be freed by the programmer (when it is no longer needed) to avoid
    --  memory leaks.
 
+   -------------------------------------
+   -- NOTE: Spawn in Tasking Programs --
+   -------------------------------------
+
+   --  Spawning processes in tasking programs using the above Spawn and
+   --  Non_Blocking_Spawn subprograms is not recommended, because there are
+   --  subtle interactions between creating a process and signals/locks that
+   --  can cause trouble. These issues are not specific to Ada; they depend
+   --  primarily on the operating system.
+
+   --  If you need to spawn processes in a tasking program, you will need to
+   --  understand the semantics of your operating system, and you are likely to
+   --  write non-portable code, because operating systems differ in this area.
+
+   --  The Spawn and Non_Blocking_Spawn subprograms call the following
+   --  operating system functions:
+
+   --     On Windows: spawnvp (blocking) or CreateProcess (non-blocking)
+
+   --     On Solaris: fork1, followed in the child process by execv
+
+   --     On other Unix-like systems, and on VMS: fork, followed in the child
+   --     process by execv.
+
+   --     On vxworks, nucleus, and RTX, spawning of processes is not supported
+
+   --  For details, look at the functions __gnat_portable_spawn and
+   --  __gnat_portable_no_block_spawn in adaint.c.
+
+   --  You should read the operating-system-specific documentation for the
+   --  above functions, paying special attention to subtle interactions with
+   --  threading, signals, locks, and file descriptors. Most of the issues are
+   --  related to the fact that on Unix, there is a window of time between fork
+   --  and execv; Windows does not have this problem, because spawning is done
+   --  in a single operation.
+
+   --  On Posix-compliant systems, such as Linux, fork duplicates just the
+   --  calling thread. (On Solaris, fork1 is the Posix-compliant version of
+   --  fork.)
+
+   --  You should avoid using signals while spawning. This includes signals
+   --  used internally by the Ada run-time system, such as timer signals used
+   --  to implement delay statements.
+
+   --  It is best to spawn any subprocesses very early, before the parent
+   --  process creates tasks, locks, or installs signal handlers. Certainly
+   --  avoid doing simultaneous spawns from multiple threads of the same
+   --  process.
+
+   --  There is no problem spawning a subprocess that uses tasking: the
+   --  problems are caused only by tasking in the parent.
+
+   --  If the parent is using tasking, and needs to spawn subprocesses at
+   --  arbitrary times, one technique is for the parent to spawn (very early)
+   --  a particular spawn-manager subprocess whose job is to spawn other
+   --  processes. The spawn-manager avoids tasking. The parent sends messages
+   --  to the spawn-manager requesting it to spawn processes, using whatever
+   --  inter-process communication mechanism you like, such as sockets.
+
+   --  In short, mixing spawning of subprocesses with tasking is a tricky
+   --  business, and should be avoided if possible, but if it is necessary,
+   --  the above guidelines should be followed, and you should beware of
+   --  portability problems.
+
    -------------------
    -- Miscellaneous --
    -------------------