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 upon which the command operates. gid 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 containing 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 TotalView returns lists of elements in P/T sets.

thread_or_process

Keywords indicating that TotalView will create a new process or thread group. You can specify one of the following arguments: t, thread, p, or process.

pattern-list

A pattern to be matched against group names. The pattern is a Tcl regular expression

Description:

The dgroups command lets you perform the following functions:

• Adds members to process and thread groups.
• Creates a group.
• Intersects a group with a set of processes and threads.
• Deletes groups.
• Displays the name and contents of groups.
• Removes members from a group.

dgroups -add

The dgroups -add command adds members to one or more thread or process groups. TotalView adds each of these threads and processes to the group. If you add a:

• Process to a thread group, TotalView adds all of its threads.
• Thread to a process group, it adds the thread's parent process.

You can abbreviate -add to -a.

The CLI returns the ID of this group.

The items being added can be explicitly named using an id-list. If you do not use an id-list, the CLI adds the threads and processes in the current focus. Similarly, you can name the group to which the CLI adds members if you use the -g option. If you omit this option, the CLI uses the groups in the current focus.

If id-list 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 specify an id-list and use the -g option, the CLI ignores the focus.

Even if you try to add the same object more than once to a group, the CLI only adds it once.

TotalView does not let you use this command to add a process to a control group. If you need to perform this operation, you can add it by using the CGROUP(dpid) variable. For example:

dset CGROUP($mypid) $new_group_id

dgroups -delete

The dgroups -delete command deletes the target group. You can only delete groups that you create; you cannot delete groups that TotalView creates.

dgroups -intersect

The dgroups -intersect command intersects a group with a set of processes and threads. If you intersect a thread group with a process, the CLI uses 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 -intersect to -i.

dgroups -list

The dgroups -list command 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 TotalView's list of group names by using the Tcl regex command.

Note:   If you do not enter a pattern, the CLI only displays groups that you have created which have nonnumeric names.

The CLI returns information from this command; it is not returned.

You can abbreviate -list to -l.

dgroups -new

The dgroups -new command creates a new thread or process group and adds threads and processes to it. If you use a name with -g, 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.

The items being added can be explicitly named using an id-list. If you do not use an id-list, the CLI adds the threads and processes in the current focus.

If id-list 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 specify an id-list and use the -g option, the CLI ignores the focus.

If you are adding more than one object and one of these objects is a duplicate, TotalView will add the non-duplicate objects to the group.

You can abbreviate -new to -n.

dgroups -remove

The dgroups -remove command removes members from one or more thread or process groups. If you ask to remove a process from a thread group, TotalView removes all of its threads. If you ask to remove a thread from a process group, TotalView 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 readonly groups such as share groups.

You can abbreviate -remove to -r.

Command alias:

You may find the following alias useful:

Alias	Definition	Meaning
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 containing 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 mygroup.

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 it; 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 its workers group.

f gW gr -i -g mygroup

Removes all nonworker threads from mygroup.

dgroups -list

dgroups -list

Tells TotalView to display information about all named groups. For example:

ODD_P: {process 1 3}
EVEN_P: {process 2 4}

gr -l *

Tells TotalView to display 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 containing 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 workers thread.