This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[PATCH 3/3] Doc
This patch is about the commands of itsets, and syntax of itset.
gdb/doc:
2012-05-03 Yao Qi <yao@codesourcery.com>
* gdb.texinfo (ITSET): New node.
(Maintenance Commands): Add for `maint info itsets'.
(ITSET Syntax): New node.
---
gdb/doc/gdb.texinfo | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 137 insertions(+), 0 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 014cfd8..582dec7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -178,6 +178,7 @@ software in general. We will miss him.
the operating system
* Trace File Format:: GDB trace file format
* Index Section Format:: .gdb_index section format
+* ITSET Syntax:: Syntax of ITSET specification
* Copying:: GNU General Public License says
how you can copy and share GDB
* GNU Free Documentation License:: The license for this documentation
@@ -3261,6 +3262,7 @@ running or not, what process it is, and why it stopped.
@menu
* Breakpoints:: Breakpoints, watchpoints, and catchpoints
* Continuing and Stepping:: Resuming execution
+* ITSET:: ITSET
* Skipping Over Functions and Files::
Skipping over functions and files
* Signals:: Signals
@@ -5129,6 +5131,65 @@ proceed until the function returns.
An argument is a repeat count, as in @code{next}.
@end table
+@node ITSET
+@section ITSET
+@cindex itset
+If a program with dozens, hundreds, or even thousands, of threads,
+@value{GDBN} needs a concept for users to refer to a certain processes,
+threads, and cores in a consistent way using a flexible syntax. This
+is called inferior/process/thread/core set construct, or inferior/thread
+set (I/T set or just itset) for short. For the details of the
+specification of ITSET syntax, @pxref{ITSET Syntax}.
+
+@subsection itset commands
+
+@table @code
+@kindex defset
+@item defset @var{name} @var{spec}
+Define a new named set.
+
+@kindex undefset @var{name}
+@item undefset @var{name}
+Undefine an existing named set.
+
+@kindex undefset -all
+@item undefset -all
+Undefine all existing named set.
+
+@kindex whichsets @r{[}@var{spec}@r{]}
+@item whichsets @r{[}@var{spec}@r{]}
+List all sets to which threads in the set @var{spec} belong to. If
+@var{spec} is not set, list all sets to all threads belong to.
+
+@smallexample
+(@value{GDBP}) whichsets t1
+i1.t1 (Thread 0x401ce6c0 (LWP 12089)) is in: stopped, all, curinf, itset-t1, itset-t1-t2
+@end smallexample
+
+@kindex viewset @r{[}@var{spec}@r{]}
+@item viewset @r{[}@var{spec}@r{]}
+List the menbers of the set @var{spec}. If @var{secp} is not set, it
+lists the members of all named sets.
+@smallexample
+(@value{GDBP}) viewset t1
+t1 contains:
+ inferiors: 1
+ threads: 1
+ cores: 3
+@end smallexample
+
+@kindex info itsets @r{[}@var{range}@r{]}
+@item info itsets @r{[}@var{range}@r{]}
+Display the list of defined named itsets. The @var{range} can not only be
+specific numbers, such as 1, 3, but also can be range, like 4-8.
+@smallexample
+(@value{GDBP}) info itsets 1 3 4-8
+@end smallexample
+
+@item @ref{maint info itsets}
+
+@end table
+
@node Skipping Over Functions and Files
@section Skipping Over Functions and Files
@cindex skipping over functions and files
@@ -34283,6 +34344,21 @@ Shared library events.
@end table
+@kindex maint info itsets
+@item @anchor{maint info itsets}maint info sets
+Diplay the list of all defined named itsets, ubser-defined and built-in.
+@smallexample
+@value{GDBP} maint info itsets
+Num Name What
+-1 running running
+-2 stopped stopped
+-3 all all
+-4 empty
+-5 curinf curinf
+1 itset-c1 c1
+2 itset-c2 c2
+@end smallexample
+
@kindex set displaced-stepping
@kindex show displaced-stepping
@cindex displaced stepping support
@@ -40225,6 +40301,67 @@ symbol.
A string in the constant pool is zero-terminated.
@end enumerate
+@node ITSET Syntax
+@appendix ITSET Syntax
+@cindex itset syntax
+This section documents the syntax of ITSET, which is used to refer to
+a set of inferiors, processes, threads and cores. This allows
+@value{GDBN} command to be applied to a set or collection of inferiors,
+processes, and threads, instead of just one thread/process or all at
+a time.
+
+@subsection Syntax
+Naturally, ITSET is composed by several @dfn{ITSET elements} and
+@dfn{ITSET operators} among them. ITSET elements are composed by
+@dfn{prefix letter}s and range or number. The table below is
+about the supported prefix letters,
+
+@multitable @columnfractions .6 .6
+@item @strong{Prefix Letter}
+@tab @strong{Description}
+@item i @tab inferior
+@item t @tab thread
+@item a @tab Ada task
+@item c @tab core
+@end multitable
+
+Since ITSET is similar to general set, the ITSET operators are
+similar to general set operators too, such as intersection
+and union. The table below is about the supported operators,
+
+@multitable @columnfractions .6 .6
+@item @strong{Operator}
+@tab @strong{Description}
+@item . @tab intersection operator
+@item , @tab union operator
+@item ~ @tab negating operator
+@item ! @tab specifies static itset
+@item $ @tab represents current itset
+@item () @tab defeat precedence
+@end multitable
+
+The syntax follow this grammar:
+@smallexample
+ ELEM = RANGE | NEG | PARENS_SET | '$' | NAME
+ NEG = '~' ELEM
+ PARENS_SET = '(' ITSET_ONE ')'
+ INTERS = ELEM ('.' ELEM)*
+ ITSET_ONE = INTERS (',' INTERS)*
+ ITSET = | ('!' ITSET_ONE) | ITSET_ONE
+@end smallexample
+
+@subsection Examples
+
+@multitable @columnfractions .6 .6
+@item @strong{ITSET} @tab @strong{Description}
+@item @var{t1-3} @tab Thread 1, 2, and 3
+@item @var{i1.t2} @tab Thread 2 in inferior 1
+@item @var{i1.t1-100.c1-2} @tab Threads 1 to 100 in inferior 1 running on core 1 to 2.
+@item @var{workers.~c1-3}
+@tab All in the user-defined set ``workers'', except those on core 1 to core 3.
+@item @var{running.i1} @tab All running threads in inferior 1
+@end multitable
+
@include gpl.texi
@node GNU Free Documentation License
--
1.7.0.4