[RFA/doco] Document task-specific breakpoints

[RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 299 bytes --]

Hello,

As promised when I sent the code patches for task-specific breakpoints,
here is the associated documentation.

2009-03-25  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Ada Tasks): Add documentation about task-specific
        breakpoints.

OK to commit?

Thanks,
-- 
Joel

[-- Attachment #2: task-tc.diff --]
[-- Type: text/x-diff, Size: 5480 bytes --]

diff --git a/gdb/testsuite/gdb.ada/tasks.exp b/gdb/testsuite/gdb.ada/tasks.exp
new file mode 100644
index 0000000..e5d9f92
--- /dev/null
+++ b/gdb/testsuite/gdb.ada/tasks.exp
@@ -0,0 +1,79 @@
+# Copyright 2009 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+if $tracelevel then {
+    strace $tracelevel
+}
+
+load_lib "ada.exp"
+
+set testdir "tasks"
+set testfile "${testdir}/foo"
+set srcfile ${srcdir}/${subdir}/${testfile}.adb
+set binfile ${objdir}/${subdir}/${testfile}
+
+file mkdir ${objdir}/${subdir}/${testdir}
+if {[gdb_compile_ada "${srcfile}" "${binfile}" executable [list debug ]] != "" } {
+  return -1
+}
+
+gdb_exit
+gdb_start
+gdb_reinitialize_dir $srcdir/$subdir
+gdb_load ${binfile}
+
+set bp_location [gdb_get_line_number "STOP_HERE" ${testdir}/foo.adb]
+runto "foo.adb:$bp_location"
+
+# Make sure that all tasks appear in the "info tasks" listing, and
+# that the active task is the environment task.
+gdb_test "info tasks" \
+         [join {"  ID       TID P-ID Pri State                  Name" \
+                "\\*  1 .* main_task" \
+                "   2 .* task_list\\(1\\)" \
+                "   3 .* task_list\\(2\\)" \
+                "   4 .* task_list\\(3\\)"} \
+               "\r\n"] \
+         "info tasks before inserting breakpoint"
+
+# Now, insert a breakpoint that should stop only if task 3 stops.
+gdb_test "break break_me task 3" "Breakpoint .* at .*"
+
+# Continue to that breakpoint.  Task 2 should hit it first, and GDB
+# is expected to ignore that hit and resume the execution.  Only then
+# task 3 will hit our breakpoint, and GDB is expected to stop at that
+# point.
+gdb_test "continue" \
+         ".*Breakpoint.*, foo.break_me \\(\\).*" \
+         "continue to breakpoint"
+
+# Check that it is indeed task 3 that hit the breakpoint by checking
+# which is the active task.
+gdb_test "info tasks" \
+         [join {"  ID       TID P-ID Pri State                  Name" \
+                "   1 .* main_task" \
+                "   2 .* task_list\\(1\\)" \
+                "\\*  3 .* task_list\\(2\\)" \
+                "   4 .* task_list\\(3\\)"} \
+               "\r\n"] \
+         "info tasks after hitting breakpoint"
+
+# Now, resume the execution and make sure that GDB does not stop when
+# task 4 hits the breakpoint. Continuing thus results in our program
+# running to completion.
+gdb_test "continue" \
+         ".*Program exited normally\..*" \
+         "continue until end of program"
+
diff --git a/gdb/testsuite/gdb.ada/tasks/foo.adb b/gdb/testsuite/gdb.ada/tasks/foo.adb
new file mode 100644
index 0000000..edf66be
--- /dev/null
+++ b/gdb/testsuite/gdb.ada/tasks/foo.adb
@@ -0,0 +1,68 @@
+--  Copyright 2009 Free Software Foundation, Inc.
+--
+--  This program is free software; you can redistribute it and/or modify
+--  it under the terms of the GNU General Public License as published by
+--  the Free Software Foundation; either version 3 of the License, or
+--  (at your option) any later version.
+--
+--  This program is distributed in the hope that it will be useful,
+--  but WITHOUT ANY WARRANTY; without even the implied warranty of
+--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+--  GNU General Public License for more details.
+--
+--  You should have received a copy of the GNU General Public License
+--  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+procedure Foo is
+
+   task type Caller is
+      entry Initialize;
+      entry Call_Break_Me;
+      entry Finalize;
+   end Caller;
+   type Caller_Ptr is access Caller;
+
+   procedure Break_Me is
+   begin
+      null;
+   end Break_Me;
+
+   task body Caller is
+   begin
+      accept Initialize do
+         null;
+      end Initialize;
+      accept Call_Break_Me do
+         Break_Me;
+      end Call_Break_Me;
+      accept Finalize do
+         null;
+      end Finalize;
+   end Caller;
+
+   Task_List : array (1 .. 3) of Caller_Ptr;
+
+begin
+
+   --  Start all our tasks, and call the "Initialize" entry to make
+   --  sure all of them have now been started.  We call that entry
+   --  immediately after having created the task in order to make sure
+   --  that we wait for that task to be created before we try to create
+   --  another one.  That way, we know that the order in our Task_List
+   --  corresponds to the order in the GNAT runtime.
+   for J in Task_List'Range loop
+      Task_List (J) := new Caller;
+      Task_List (J).Initialize;
+   end loop;
+
+   --  Next, call their Call_Break_Me entry of each task, using the same
+   --  order as the order used to create them.
+   for J in Task_List'Range loop  -- STOP_HERE
+      Task_List (J).Call_Break_Me;
+   end loop;
+
+   --  And finally, let all the tasks die...
+   for J in Task_List'Range loop
+      Task_List (J).Finalize;
+   end loop;
+end Foo;

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 322 bytes --]

[with the right patch, sorry]

Hello,

As promised when I sent the code patches for task-specific breakpoints,
here is the associated documentation.

2009-03-25  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Ada Tasks): Add documentation about task-specific
        breakpoints.

OK to commit?

-- 
Joel

[-- Attachment #2: task-doc.diff --]
[-- Type: text/x-diff, Size: 2519 bytes --]

commit a786896e6559c568c3afea276bdc240ca8814dae
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Wed Mar 25 14:42:30 2009 -0700

        * gdb.texinfo (Ada Tasks): Add documentation about task-specific
        breakpoints.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 134919d..92b4609 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -11743,6 +11743,59 @@ from the current task to the given task.
 #4  0x804aacc in un () at un.adb:5
 @end smallexample
 
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks
+@cindex task breakpoints
+@kindex break @dots{} task @var{taskno}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Set Breaks,,Setting breakpoints}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint.  @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+   2 140045060   1   15 Accept/Select Wait    t2
+   3 140044840   1   15 Runnable              t1
+*  4 140056040   1   15 Running               t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug.tB.1 (_task=0x11ffffc60)
+    at test_task_debug.adb:15
+15               flush;
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+*  2 140045060   1   15 Running               t2
+   3 140044840   1   15 Runnable              t1
+   4 140056040   1   15 Delay Sleep           t3
+@end smallexample
 @end table
 
 @node Ada Tasks and Core Files

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Wed, 25 Mar 2009 15:02:36 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> As promised when I sent the code patches for task-specific breakpoints,
> here is the associated documentation.

Thanks.

> 2009-03-25  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdb.texinfo (Ada Tasks): Add documentation about task-specific
>         breakpoints.
> 
> OK to commit?

Yes, with a few comments:

> +@cindex breakpoints and tasks

Suggest to mention Ada explicitly:

  @cindex breakpoints and tasks, in Ada

> +@cindex task breakpoints

Likewise.

> +@kindex break @dots{} task @var{taskno}

Similarly:

  @kindex break @dots{} task @var{taskno}@r{ (Ada)}

> +@var{linespec} specifies source lines, as described
> +in @ref{Set Breaks,,Setting breakpoints}.

It is better to point to "Specify Location", where @var{linespec} is
_really_ described.

> +Breakpoint 5, test_task_debug.tB.1 (_task=0x11ffffc60)
                                ^^^^^
What is this part?  Should we explain it in some footnote?  And what
about _task=0x11ffffc60 part, should it perhaps be explained, too?

> +(@value{GDBP}) info tasks
> +  ID       TID P-ID Pri State                 Name
> +   1 140022020   0   15 Child Activation Wait main_task
> +*  2 140045060   1   15 Running               t2

"Running"? shouldn't it be stopped at breakpoint?

Finally, please add a cross-reference to here in the "Set Breaks"
node, saying that Ada supports thread-specific breakpoints.

Thanks.

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 1238 bytes --]

Hello Eli,

> > +Breakpoint 5, test_task_debug.tB.1 (_task=0x11ffffc60)
>                                 ^^^^^
> What is this part?  Should we explain it in some footnote?  And what
> about _task=0x11ffffc60 part, should it perhaps be explained, too?

Hmm, good point. These are actually old compiler artifacts that we
got rid of since writing that documentation.  The original testcase
was using what we call a task "entry" I believe, which is the reason
for the "_task" parameter. We could just as well have used a function
so I cleaned up the example to make it simpler.

> > +(@value{GDBP}) info tasks
> > +  ID       TID P-ID Pri State                 Name
> > +   1 140022020   0   15 Child Activation Wait main_task
> > +*  2 140045060   1   15 Running               t2
> 
> "Running"? shouldn't it be stopped at breakpoint?

In practice, yes, it is stopped. But this information is printed
from the point of view of the runtime. To the runtime, task "t2"
is running.

Attached is a new version of the documentation patch:

        * gdb.texinfo (Ada Tasks): Add documentation about task-specific
        breakpoints.
        (Set Breaks): Add reference to thread-specific and task-specific
        breakpoints.

Thanks,
-- 
Joel

[-- Attachment #2: task-doc.diff --]
[-- Type: text/x-diff, Size: 2853 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 134919d..77b522b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3051,6 +3051,11 @@ C@t{++}, a function name may refer to more than one possible place to break.
 @xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
 that situation.
 
+It is also possible to insert a breakpoint that will stop the program
+only if a specific thread or a specific task hits that breakpoint.
+@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
+information about this feature.
+
 @item break
 When called without any arguments, @code{break} sets a breakpoint at
 the next instruction to be executed in the selected stack frame
@@ -11743,6 +11748,58 @@ from the current task to the given task.
 #4  0x804aacc in un () at un.adb:5
 @end smallexample
 
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks, in Ada
+@cindex task breakpoints, in Ada
+@kindex break @dots{} task @var{taskno}@r{ (Ada)}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Specify Location}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint.  @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+   2 140045060   1   15 Accept/Select Wait    t2
+   3 140044840   1   15 Runnable              t1
+*  4 140056040   1   15 Running               t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug () at test_task_debug.adb:15
+15               flush;
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+*  2 140045060   1   15 Running               t2
+   3 140044840   1   15 Runnable              t1
+   4 140056040   1   15 Delay Sleep           t3
+@end smallexample
 @end table
 
 @node Ada Tasks and Core Files

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Thu, 26 Mar 2009 15:39:02 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > > +(@value{GDBP}) info tasks
> > > +  ID       TID P-ID Pri State                 Name
> > > +   1 140022020   0   15 Child Activation Wait main_task
> > > +*  2 140045060   1   15 Running               t2
> > 
> > "Running"? shouldn't it be stopped at breakpoint?
> 
> In practice, yes, it is stopped. But this information is printed
> from the point of view of the runtime. To the runtime, task "t2"
> is running.

Sorry, I don't understand.  Can you elaborate?

> Attached is a new version of the documentation patch:
> 
>         * gdb.texinfo (Ada Tasks): Add documentation about task-specific
>         breakpoints.
>         (Set Breaks): Add reference to thread-specific and task-specific
>         breakpoints.

OK, but I think the "running" part should be either fixed or
explained.

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

> > > > +(@value{GDBP}) info tasks
> > > > +  ID       TID P-ID Pri State                 Name
> > > > +   1 140022020   0   15 Child Activation Wait main_task
> > > > +*  2 140045060   1   15 Running               t2
> > > 
> > > "Running"? shouldn't it be stopped at breakpoint?
> > 
> > In practice, yes, it is stopped. But this information is printed
> > from the point of view of the runtime. To the runtime, task "t2"
> > is running.
> 
> Sorry, I don't understand.  Can you elaborate?

Sure. These states indicate what the tasks are currently doing.
For instance "Child activation wait" above means that the task
is waiting for its children to complete before it terminates
(see the description of these state in the Manual). "Running"
is another one of these states which just says that, from the
point of view of the program, that this task is not waiting
for an event, nor sleeping, nor waiting for a rendez-vous, etc.
It's simply executing some code.

> > Attached is a new version of the documentation patch:
> > 
> >         * gdb.texinfo (Ada Tasks): Add documentation about task-specific
> >         breakpoints.
> >         (Set Breaks): Add reference to thread-specific and task-specific
> >         breakpoints.
> 
> OK, but I think the "running" part should be either fixed or
> explained.

I think that "Running" is fine and doesn't need fixing. So let me know
if you'd like me to explain further.

-- 
Joel

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Fri, 27 Mar 2009 08:34:41 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> "Running"
> is another one of these states which just says that, from the
> point of view of the program, that this task is not waiting
> for an event, nor sleeping, nor waiting for a rendez-vous, etc.
> It's simply executing some code.

But in fact, it isn't executing some code, it's stopped at a
breakpoint, isn't it?  If it is executing code, what code is that?

> > OK, but I think the "running" part should be either fixed or
> > explained.
> 
> I think that "Running" is fine and doesn't need fixing.

If I were the user looking at the "Running" status, I'd certainly
think that something is dead wrong with this task-specific breakpoint.

Re: [RFA/doco] Document task-specific breakpoints

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Joel> "Running"
Joel> is another one of these states which just says that, from the
Joel> point of view of the program, that this task is not waiting
Joel> for an event, nor sleeping, nor waiting for a rendez-vous, etc.
Joel> It's simply executing some code.

Eli> But in fact, it isn't executing some code, it's stopped at a
Eli> breakpoint, isn't it?  If it is executing code, what code is that?

It is displaying the state as the program sees it, not gdb's view of
the task.

Perhaps the documentation can explain why a stopped task might say
"running".

Tom

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

> But in fact, it isn't executing some code, it's stopped at a
> breakpoint, isn't it?  If it is executing code, what code is that?
[...]
> If I were the user looking at the "Running" status, I'd certainly
> think that something is dead wrong with this task-specific breakpoint.

It's been a naming convention that we have been using for 10+ years.
So far, we have had no report about this, either customer or internal.
Customer support is at the heart of our business, so we are fairly
pro-active at encouraging our customers in sending reports.

It does NOT mean that you're wrong, but I do disagree with you on this
one and I definitely feel like being dragged in a bikeshed discussion.
So, unless others also think that this is confusing, I'm not going to
change GDB, but I'll agree to change the documentation instead.

The problem is that I don't understand what it is that is so confusing
to you. I understand that the task is not executing code precisely
at the moment where the state was printed, but it was just before
the program was stopped, and it will when the program is resumed.

What I propose, at this stage, is that you look at the documentation
in the GDB manual, and update the description of the "Running" state
to provide whatever piece of information you think needs to be added.
I can do that for you if you tell me what you want to me add.

-- 
Joel

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

Eli,

> What I propose, at this stage, is that you look at the documentation
> in the GDB manual, and update the description of the "Running" state
> to provide whatever piece of information you think needs to be added.
> I can do that for you if you tell me what you want to me add.

Let's hold off on that suggestion, as others have now expressed
the same opinion. I'm exploring various options. Will get back to you.

-- 
Joel

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Fri, 27 Mar 2009 09:10:51 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> The problem is that I don't understand what it is that is so confusing
> to you.

What is confusing is this:

    (@value{GDBP}) info tasks
      ID       TID P-ID Pri State                 Name
       1 140022020   0   15 Child Activation Wait main_task
       2 140045060   1   15 Accept/Select Wait    t2
       3 140044840   1   15 Runnable              t1
    *  4 140056040   1   15 Running               t3

Task 2 is running, okay.

    (@value{GDBP}) b 15 task 2
    Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.

Set a breakpoint for task 2.

    Breakpoint 5, test_task_debug () at test_task_debug.adb:15

Breakpoint is hit by task 2.

    (@value{GDBP}) info tasks
      ID       TID P-ID Pri State                 Name
       1 140022020   0   15 Child Activation Wait main_task
    *  2 140045060   1   15 Running               t2
       3 140044840   1   15 Runnable              t1
       4 140056040   1   15 Delay Sleep           t3

And task 2 is still running, even though it has hit the breakpoint.

Did I succeed in explaining what is confusing?  The task was running,
then it hit the breakpoint, but it is still "running".

If this is normal, at least remove the second "info tasks" and its
output from the example.

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 270 bytes --]

> 2009-03-25  Joel Brobecker  <brobecker@adacore.com>
> 
>         * gdb.texinfo (Ada Tasks): Add documentation about task-specific
>         breakpoints.

I checked this patch in, with "Running" changed to "Runnable".
For the record, here is the final patch.

-- 
Joel

[-- Attachment #2: tasks-bp-doc.diff --]
[-- Type: text/x-diff, Size: 2853 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a1c0b80..8b1467e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3051,6 +3051,11 @@ C@t{++}, a function name may refer to more than one possible place to break.
 @xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
 that situation.
 
+It is also possible to insert a breakpoint that will stop the program
+only if a specific thread or a specific task hits that breakpoint.
+@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
+information about this feature.
+
 @item break
 When called without any arguments, @code{break} sets a breakpoint at
 the next instruction to be executed in the selected stack frame
@@ -11750,6 +11755,58 @@ from the current task to the given task.
 #4  0x804aacc in un () at un.adb:5
 @end smallexample
 
+@item break @var{linespec} task @var{taskno}
+@itemx break @var{linespec} task @var{taskno} if @dots{}
+@cindex breakpoints and tasks, in Ada
+@cindex task breakpoints, in Ada
+@kindex break @dots{} task @var{taskno}@r{ (Ada)}
+These commands are like the @code{break @dots{} thread @dots{}}
+command (@pxref{Thread Stops}).
+@var{linespec} specifies source lines, as described
+in @ref{Specify Location}.
+
+Use the qualifier @samp{task @var{taskno}} with a breakpoint command
+to specify that you only want @value{GDBN} to stop the program when a
+particular Ada task reaches this breakpoint.  @var{taskno} is one of the
+numeric task identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info tasks} display.
+
+If you do not specify @samp{task @var{taskno}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
+
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @samp{task @var{taskno}} before the
+breakpoint condition (before the @code{if}).
+
+For example,
+
+@smallexample
+@iftex
+@leftskip=0.5cm
+@end iftex
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+   2 140045060   1   15 Accept/Select Wait    t2
+   3 140044840   1   15 Runnable              t1
+*  4 140056040   1   15 Runnable              t3
+(@value{GDBP}) b 15 task 2
+Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
+(@value{GDBP}) cont
+Continuing.
+task # 1 running
+task # 2 running
+
+Breakpoint 5, test_task_debug () at test_task_debug.adb:15
+15               flush;
+(@value{GDBP}) info tasks
+  ID       TID P-ID Pri State                 Name
+   1 140022020   0   15 Child Activation Wait main_task
+*  2 140045060   1   15 Runnable              t2
+   3 140044840   1   15 Runnable              t1
+   4 140056040   1   15 Delay Sleep           t3
+@end smallexample
 @end table
 
 @node Ada Tasks and Core Files

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Tue, 31 Mar 2009 09:55:13 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> > 2009-03-25  Joel Brobecker  <brobecker@adacore.com>
> > 
> >         * gdb.texinfo (Ada Tasks): Add documentation about task-specific
> >         breakpoints.
> 
> I checked this patch in, with "Running" changed to "Runnable".
> For the record, here is the final patch.

Thanks.

I wonder: would it make sense to add to this text elsewhere in the
manual:

 @item Runnable
 The task is not blocked for any reason known to Ada.  (It may be waiting
 for a mutex, though.) It is conceptually "executing" in normal mode.

something that mentions the possibility that the task could be stopped
at a breakpoint, not only waiting for a mutex?

Re: [RFA/doco] Document task-specific breakpoints

[Tom Tromey]

>>>>> "Joel" == Joel Brobecker <brobecker@adacore.com> writes:

Today I noticed that this patch causes a warning:

Joel> +It is also possible to insert a breakpoint that will stop the program
Joel> +only if a specific thread or a specific task hits that breakpoint.
Joel> +@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more

../../../archer/gdb/doc/gdb.texinfo:3057: warning: `.' or `,' must follow @xref, not `a'.

I'm using makeinfo 4.11.

Tom

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

> Joel> +It is also possible to insert a breakpoint that will stop the program
> Joel> +only if a specific thread or a specific task hits that breakpoint.
> Joel> +@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
> 
> ../../../archer/gdb/doc/gdb.texinfo:3057: warning: `.' or `,' must follow @xref, not `a'.

Umpf :-(, sorry about that. Is it OK if I add a coma after the xref.
It'd look like this:

    See Thread-Specific Breakpoints, and Ada Tasks for more [...]

I would have prefered the current version, though. Perhaps we need
to change the way we wrote the references?

-- 
Joel

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Thu, 9 Apr 2009 09:59:26 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> > Joel> +It is also possible to insert a breakpoint that will stop the program
> > Joel> +only if a specific thread or a specific task hits that breakpoint.
> > Joel> +@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
> > 
> > ../../../archer/gdb/doc/gdb.texinfo:3057: warning: `.' or `,' must follow @xref, not `a'.
> 
> Umpf :-(, sorry about that. Is it OK if I add a coma after the xref.

Yes, that's the canonical way of handling this.  Note that @ref also
needs a comma after its argument.

>     See Thread-Specific Breakpoints, and Ada Tasks for more [...]
> 
> I would have prefered the current version, though.

Right, but this is a limitation of Texinfo.

> Perhaps we need to change the way we wrote the references?

In general, it is not a very good idea to have several
cross-references to close in the same sentence.  Something like the
following might be better:

  @xref{Thread-Specific Breakpoints}, for more about this.  For
  Ada-specific aspects, see @ref{Ada Tasks}.

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

> In general, it is not a very good idea to have several
> cross-references to close in the same sentence.  Something like the
> following might be better:
> 
>   @xref{Thread-Specific Breakpoints}, for more about this.  For
>   Ada-specific aspects, see @ref{Ada Tasks}.

I agree with what you are saying, except that I think that the actual
suggestion does not flow well with the way the paragraph is written.
Currently, we have:

    It is also possible to insert a breakpoint that will stop the program
    only if a specific thread or a specific task hits that breakpoint.
    @xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
    information about this feature.

Basically, we say: thread-specific breakpoint, or task-specific
breakpoint.  Then xref thread-specific. Then xref task-specific.
Perhaps it'd be better to move the reference links to where the actual
reference is. But I couldn't find a way that satisfied me either.

So I propose the following in the end:

    It is also possible to insert a breakpoint that will stop the program
    only if a specific thread or a specific task hits that breakpoint.
    @xref{Thread-Specific Breakpoints}, and @ref{Ada Tasks}, for more
    information about this feature.

(adding the coma after each ref).

WDYT?

Thanks,
-- 
Joel

Re: [RFA/doco] Document task-specific breakpoints

[Eli Zaretskii]

> Date: Thu, 9 Apr 2009 10:33:04 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: tromey@redhat.com, gdb-patches@sourceware.org
> 
> >   @xref{Thread-Specific Breakpoints}, for more about this.  For
> >   Ada-specific aspects, see @ref{Ada Tasks}.
> 
> I agree with what you are saying, except that I think that the actual
> suggestion does not flow well with the way the paragraph is written.
> Currently, we have:
> 
>     It is also possible to insert a breakpoint that will stop the program
>     only if a specific thread or a specific task hits that breakpoint.
>     @xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
>     information about this feature.
> 
> Basically, we say: thread-specific breakpoint, or task-specific
> breakpoint.  Then xref thread-specific. Then xref task-specific.

In that case, how about

     It is also possible to insert a breakpoint that will stop the program
     only if a specific thread or a specific task hits that breakpoint.
     @xref{Thread-Specific Breakpoints}, for more information about
     thread-specific breakpoints; see @ref{Ada Tasks}, for more
     information about task-specific breakpoints.

or

     It is also possible to insert a breakpoint that will stop the program
     only if a specific thread (@pxref{Thread-Specific Breakpoints})
     or a specific task (@pxref{Ada Tasks}) hits that breakpoint.

> So I propose the following in the end:
> 
>     It is also possible to insert a breakpoint that will stop the program
>     only if a specific thread or a specific task hits that breakpoint.
>     @xref{Thread-Specific Breakpoints}, and @ref{Ada Tasks}, for more
>     information about this feature.

That's also OK.

Re: [RFA/doco] Document task-specific breakpoints

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 478 bytes --]

>      It is also possible to insert a breakpoint that will stop the program
>      only if a specific thread (@pxref{Thread-Specific Breakpoints})
>      or a specific task (@pxref{Ada Tasks}) hits that breakpoint.

I like this suggestion best, so this is what I checked in. Thanks
a lot!

2009-04-09  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Set Breaks): Rewrite a paragraph to avoid a warning
        about a missing dot or coma after @xref.

-- 
Joel

[-- Attachment #2: doc.diff --]
[-- Type: text/x-diff, Size: 810 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.578
diff -u -p -r1.578 gdb.texinfo
--- gdb.texinfo	2 Apr 2009 15:56:08 -0000	1.578
+++ gdb.texinfo	9 Apr 2009 20:10:18 -0000
@@ -3052,9 +3052,8 @@ C@t{++}, a function name may refer to mo
 that situation.
 
 It is also possible to insert a breakpoint that will stop the program
-only if a specific thread or a specific task hits that breakpoint.
-@xref{Thread-Specific Breakpoints} and @ref{Ada Tasks} for more
-information about this feature.
+only if a specific thread (@pxref{Thread-Specific Breakpoints})
+or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
 
 @item break
 When called without any arguments, @code{break} sets a breakpoint at