dgroups
Manipulates and manages groups
Format
Adds members to thread and process groups
dgroups -add [ -g gid ] [ id-list ]
Deletes groups
dgroups -delete [ -g gid ]
Intersects a group with a list of processes and threads
dgroups -intersect [ -g gid ] [ id-list ]
Prints process and thread group information
dgroups [ -list ] [ pattern-list ]
Creates a new thread or process group
dgroups -new [ thread_or_process ] [ -g gid ] [ id-list ]
Removes members from thread or process groups
dgroups -remove [ -g gid ] [ id-list ]
Arguments
-g gid
The group ID on which the command operates. The gid value can be an existing numeric group ID, an existing group name, or, if you are using the -new option, a new group name.
id-list
A Tcl list that contains process and thread IDs. Process IDs are integers; for example, 2 indicates process 2. Thread IDs define a
pid.
tid pair and look like decimal numbers; for example, 2.3 indicates process 2, thread 3. If the first element of this list is a group tag, such as the word
control, the CLI ignores it. This makes it easy to insert all members of an existing group as the items to be used in any of these operations. (See the
dset command’s discussion of the
GROUP(gid) variable for information on group designators.) These words appear in some circumstances when the CLI returns lists of elements in P/T sets.
pattern-list
A pattern to be matched against group names. The pattern is a Tcl regular expression.
thread_or_process
Keywords that create a new process or thread group. You can specify one of the following arguments: t, thread, p, or process.
Description
The dgroups command supports the following functions:
• Adding members to process and thread groups.
• Creating a group.
• Intersecting a group with a set of processes and threads.
• Deleting groups.
• Displaying the name and contents of groups.
• Removing members from a group.
dgroups -add
Adds members to one or more thread or process groups. The CLI adds each of these threads and processes to the group. If you add a:
• Process to a thread group, the CLI adds all of its threads.
• Thread to a process group, the CLI adds the thread’s parent process.
You can abbreviate the -add option to -a.
The CLI returns the ID of this group.
You can explicitly name the items being added by using an id-list argument. Without an id-list argument, the CLI adds the threads and processes in the current focus. Similarly, you can name the group using the -g option. Without the -g option, the CLI uses the groups in the current focus.
If the id-list argument contains processes, and the target is a thread group, the CLI adds all threads from these processes. If it contains threads and the target is a process group, the CLI adds the parent process for each thread.
NOTE >> If you specify an id-list argument and you also use the -g option, the CLI ignores the focus. You can use two dgroups -add commands instead.
If you try to add the same object more than once to a group, the CLI adds it only once.
You cannot use this command to add a process to a control group. Instead, use the CGROUP(dpid) variable; for example:
dset CGROUP($mypid) $new_group_id
dgroups -delete
Deletes the target group. You can delete only groups that you create; you cannot delete groups that TotalView creates.
dgroups -intersect
Intersects a group with a set of processes and threads. If you intersect a thread group with a process, the CLI includes all of the process’s threads. If you intersect a process group with a thread, the CLI uses the thread’s process.
After this command executes, the group no longer contains members that were not in this intersection.
You can abbreviate the -intersect option to -i.
dgroups -list
Prints the name and contents of process and thread groups. If you specify a pattern-list as an argument, the CLI only prints information about groups whose names match this pattern. When entering a list, you can specify a pattern. The CLI matches this pattern against the list of group names by using the Tcl regex command.
NOTE >> If you do not enter a pattern, the CLI displays only groups that you have created with nonnumeric names.
You can abbreviate -list to -l.
dgroups -new
Creates a new thread or process group and adds threads and processes to it. If you use a name with the -g option, the CLI uses that name for the group ID; otherwise, it assigns a new numeric ID. If the group you name already exists, the CLI replaces it with the newly created group.
The CLI returns the ID of the newly created group.
You can explicitly name the items being added with an id-list argument. If you do not use an id-list argument, the CLI adds the threads and processes in the current focus.
If the id-list argument contains processes, and the target is a thread group, the CLI adds all threads from these processes. If it contains threads and the target is a process group, TotalView adds the parent process for each thread.
NOTE >> If you use an id-list argument and also use the -g option, the CLI ignores the focus.You can use two dgroups -add commands instead.
If you are adding more than one object and one of these objects is a duplicate, The CLI adds the nonduplicate objects to the group.
You can abbreviate the -new option to -n.
dgroups -remove
Removes members from one or more thread or process groups. If you remove a process from a thread group, The CLI removes all of its threads. If remove a thread from a process group, The CLI removes its parent process.
You cannot remove processes from a control group. You can, however, move a process from one control group to another by using the
dset command to assign it to the CGROUP(dpid) variable group.
Also, you cannot use this command on read-only groups, such as share groups.
You can abbreviate the -remove option to -r.
Command alias
Alias | Definition | Description |
gr | dgroups | Manipulates a group |
Examples
dgroups -add
f tW gr -add
Adds the focus thread to its workers group.
dgroups -add
Adds the current focus thread to the current focus group.
set gid [dgroups -new thread ($CGROUP(1))]
Creates a new thread group that contains all threads from all processes in the control group for process 1.
f $a_group/9 dgroups -add
Adds process 9 to a user-defined group.
dgroups -delete
gr -delete -g mygroup
Deletes the mygroup group.
dgroups -intersect
dgroups -intersect -g 3 3.2
Intersects thread 3.2 with group 3. If group 3 is a thread group, this command removes all threads except 3.2 from the group; if it is a process group, this command removes all processes except process 3 from it.
f tW gr -i
Intersects the focus thread with the threads in its workers group.
f gW gr -i -g mygroup
Removes all nonworker threads from the mygroup group.
dgroups -list
dgroups -list
Displays information about all named groups; for example:
ODD_P: {process 1 3}
EVEN_P: {process 2 4}
gr -l *
Displays information about groups in the current focus.
1: {control 1 2 3 4}
2: {workers 1.1 1.2 1.3 1.4 2.1 2.2 2.3 2.4 3.1
3.2 3.3 3.4 4.1 4.2 4.3 4.4}
3: {share 1 2 3 4}
ODD_P: {process 1 3}
EVEN_P: {process 2 4}
dgroups -new
gr -n t -g mygroup $GROUP($CGROUP(1))
Creates a new thread group named mygroup that contains all threads from all processes in the control group for process 1.
set mygroup [dgroups -new]
Creates a new process group that contains the current focus process.
dgroups -remove
dgroups -remove -g 3 3.2
Removes thread 3.2 from group 3.
f W dgroups -add
Marks the current thread as being a worker thread.
f W dgroups -r
Indicates that the current thread is not a worker thread.
Related Topics