"{ Package: 'jv:libgdbs' }"

GDBMICommand subclass:#GDBMI_list_thread_groups

	instanceVariableNames:''

	classVariableNames:''

	poolDictionaries:''

	category:'GDB-Core-Commands-MI'

!

!GDBMI_list_thread_groups class methodsFor:'documentation'!

documentation

"

The `-list-thread-groups' Command

---------------------------------

Synopsis

--------

     -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]

   Lists thread groups (*note Thread groups::).  When a single thread

group is passed as the argument, lists the children of that group.

When several thread group are passed, lists information about those

thread groups.  Without any parameters, lists information about all

top-level thread groups.

   Normally, thread groups that are being debugged are reported.  With

the `--available' option, {No value for `GDBN'} reports thread groups

available on the target.

   The output of this command may have either a `threads' result or a

`groups' result.  The `thread' result has a list of tuples as value,

with each tuple describing a thread (*note GDB/MI Thread

Information::).  The `groups' result has a list of tuples as value,

each tuple describing a thread group.  If top-level groups are

requested (that is, no parameter is passed), or when several groups are

passed, the output always has a `groups' result.  The format of the

`group' result is described below.

   To reduce the number of roundtrips it's possible to list thread

groups together with their children, by passing the `--recurse' option

and the recursion depth.  Presently, only recursion depth of 1 is

permitted.  If this option is present, then every reported thread group

will also include its children, either as `group' or `threads' field.

   In general, any combination of option and parameters is permitted,

with the following caveats:

   * When a single thread group is passed, the output will typically be

     the `threads' result.  Because threads may not contain anything,

     the `recurse' option will be ignored.

   * When the `--available' option is passed, limited information may

     be available.  In particular, the list of threads of a process

     might be inaccessible.  Further, specifying specific thread groups

     might not give any performance advantage over listing all thread

     groups.  The frontend should assume that `-list-thread-groups

     --available' is always an expensive operation and cache the

     results.

   The `groups' result is a list of tuples, where each tuple may have

the following fields:

`id'

     Identifier of the thread group.  This field is always present.

     The identifier is an opaque string; frontends should not try to

     convert it to an integer, even though it might look like one.

`type'

     The type of the thread group.  At present, only `process' is a

     valid type.

`pid'

     The target-specific process identifier.  This field is only present

     for thread groups of type `process' and only if the process exists.

`num_children'

     The number of children this thread group has.  This field may be

     absent for an available thread group.

`threads'

     This field has a list of tuples as value, each tuple describing a

     thread.  It may be present if the `--recurse' option is specified,

     and it's actually possible to obtain the threads.

`cores'

     This field is a list of integers, each identifying a core that one

     thread of the group is running on.  This field may be absent if

     such information is not available.

`executable'

     The name of the executable file that corresponds to this thread

     group.  The field is only present for thread groups of type

     `process', and only if there is a corresponding executable file.

Example

-------

     {No value for `GDBP'}

     -list-thread-groups

     ^done,groups=[{id='17',type='process',pid='yyy',num_children='2'}]

     -list-thread-groups 17

     ^done,threads=[{id='2',target-id='Thread 0xb7e14b90 (LWP 21257)',

        frame={level='0',addr='0xffffe410',func='__kernel_vsyscall',args=[]},state='running'},

     {id='1',target-id='Thread 0xb7e156b0 (LWP 21254)',

        frame={level='0',addr='0x0804891f',func='foo',args=[{name='i',value='10'}],

                file='/tmp/a.c',fullname='/tmp/a.c',line='158'},state='running'}]]

     -list-thread-groups --available

     ^done,groups=[{id='17',type='process',pid='yyy',num_children='2',cores=[1,2]}]

     -list-thread-groups --available --recurse 1

      ^done,groups=[{id='17', types='process',pid='yyy',num_children='2',cores=[1,2],

                     threads=[{id='1',target-id='Thread 0xb7e14b90',cores=[1]},

                              {id='2',target-id='Thread 0xb7e14b90',cores=[2]}]},..]

     -list-thread-groups --available --recurse 1 17 18

     ^done,groups=[{id='17', types='process',pid='yyy',num_children='2',cores=[1,2],

                    threads=[{id='1',target-id='Thread 0xb7e14b90',cores=[1]},

                             {id='2',target-id='Thread 0xb7e14b90',cores=[2]}]},...]

"

! !

!GDBMI_list_thread_groups methodsFor:'accessing'!

operation

	^ 'list-thread-groups'

! !