Класс ThreadGroup

java.lang.Object

java.lang.ThreadGroup

Все реализованные интерфейсы:: Thread.UncaughtExceptionHandler

public class ThreadGroup extends Object implements Thread.UncaughtExceptionHandler

Группа потоков представляет собой набор потоков. Кроме того, группа потоков может также включать другие группы потоков. Группы потоков образуют дерево, в котором каждая группа потоков, кроме начальной группы потоков, имеет родителя.

Группа потоков имеет имя и максимальный приоритет. Имя задается при создании группы и изменить его нельзя. Максимальный приоритет группы — это максимальный приоритет для потоков, созданных в группе. Изначально он наследуется от родительской группы потоков, но может быть изменен с помощью метода setMaxPriority.

Группа потоков слабо доступна из родительской группы, поэтому она может быть кандидатом на сборку мусора, когда в группе нет активных потоков, и группа потоков иначе недоступна.

Если не указано иное, передача null аргумента в конструктор или метод в этом классе приведет к тому, что будет брошено исключение NullPointerException.

Группы потоков и виртуальные потоки

Java runtime создает специальную группу потоков для виртуальных потоков. Эта группа возвращается методом Thread.getThreadGroup, когда он вызывается для виртуального потока. Группа потоков отличается от других групп потоков тем, что ее максимальный приоритет фиксирован и не может быть изменен методом setMaxPriority. Виртуальные потоки не включаются в оценку количества потоков, возвращаемой методом activeCount, не перечисляются методом enumerate и не прерываются методом interrupt.

Примечание API:: Группы потоков предоставляли способ в ранних выпусках Java для группировки потоков и предоставления формы управления задачами для потоков. Группы потоков поддерживали изоляцию апплетов и определяли методы, предназначенные для диагностических целей. Для новых приложений следует редко создавать ThreadGroups и взаимодействовать с этим API.
C момента:: 1.0

Краткое описание конструкторов

Конструктор	Описание
`ThreadGroup(String name)`	Создает новую группу потоков.
`ThreadGroup(ThreadGroup parent, String name)`	Создает новую группу потоков.

Краткое описание методов

Модификатор и тип	Метод	Описание
`int`	`activeCount()`	Возвращает оценку количества активных платформенных потоков в этой группе потоков и ее подгруппах.
`int`	`activeGroupCount()`	Возвращает оценку количества групп в этой группе потоков и ее подгруппах.
`final void`	`checkAccess()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод полезен только в сочетании с Security Manager, который устарел и подлежит удалению в будущей версии.
`final void`	`destroy()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально предназначался для уничтожения пустой группы потоков.
`int`	`enumerate(Thread[] list)`	Копирует в указанный массив каждый активный платформенный поток в этой группе потоков и ее подгруппах.
`int`	`enumerate(Thread[] list, boolean recurse)`	Копирует в указанный массив каждый активный платформенный поток в этой группе потоков.
`int`	`enumerate(ThreadGroup[] list)`	Копирует в указанный массив ссылки на каждую подгруппу в этой группе потоков и ее подгруппах.
`int`	`enumerate(ThreadGroup[] list, boolean recurse)`	Копирует в указанный массив ссылки на каждую подгруппу в этой группе потоков.
`final int`	`getMaxPriority()`	Возвращает максимальный приоритет этой группы потоков.
`final String`	`getName()`	Возвращает имя этой группы потоков.
`final ThreadGroup`	`getParent()`	Возвращает родителя этой группы потоков.
`final void`	`interrupt()`	Прерывает все активные платформенные потоки в этой группе потоков и ее подгруппах.
`final boolean`	`isDaemon()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально указывал, является ли группа потоков группой демон-потоков, которая автоматически уничтожается, когда завершается последний поток.
`boolean`	`isDestroyed()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально указывал, уничтожается ли группа потоков.
`void`	`list()`	Выводит информацию об этой группе потоков в стандартный вывод.
`final boolean`	`parentOf(ThreadGroup g)`	Проверяет, является ли эта группа потоков группой потоков-аргументов или одной из ее родительских групп потоков.
`final void`	`resume()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально предназначался для возобновления всех потоков в группе потоков.
`final void`	`setDaemon(boolean daemon)`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально настраивал, является ли группа потоков группой демон-потоков, которая автоматически уничтожается, когда завершается последний поток.
`final void`	`setMaxPriority(int pri)`	Устанавливает максимальный приоритет группы.
`final void`	`stop()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально предназначался для остановки всех потоков в группе потоков.
`final void`	`suspend()`	Устаревший, подлежит удалению: Этот элемент API может быть удален в будущей версии. Этот метод изначально предназначался для приостановки всех потоков в группе потоков.
`String`	`toString()`	Возвращает строковое представление этой группы потоков.
`void`	`uncaughtException(Thread t, Throwable e)`	Вызывается Java Virtual Machine, когда поток в этой группе потоков останавливается из-за необработанного исключения, и у потока нет установленного `Thread.UncaughtExceptionHandler`.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Подробное описание конструкторов

ThreadGroup

public ThreadGroup(String name)

Создает новую группу потоков. Родительской группой для этой новой группы является группа потоков текущего выполняющегося потока.

Метод checkAccess родительской группы потоков вызывается без аргументов; это может привести к исключению безопасности.

Параметры:

name - имя новой группы потоков, может быть null

Исключения:

SecurityException - если текущий поток не может создать поток в заданной группе потоков.

См. также:

ThreadGroup

public ThreadGroup(ThreadGroup parent, String name)

Создает новую группу потоков. Родительской группой для этой новой группы является указанная группа потоков.

Параметры:

parent - родительская группа потоков.

name - имя новой группы потоков, может быть null

Исключения:

SecurityException - если текущий поток не может создать поток в заданной группе потоков.

См. также:

Подробное описание методов

getName

public final String getName()

Возвращает имя этой группы потоков.

Возвращает:: имя этой группы потоков, может быть null

getParent

public final ThreadGroup getParent()

Возвращает родителя этой группы потоков.

Сначала, если родитель не null, метод checkAccess родительской группы потоков вызывается без аргументов; это может привести к исключению безопасности.

Возвращает:

родителя этой группы потоков. Группа потоков верхнего уровня - единственная группа потоков, у которой родитель null.

Исключения:

SecurityException - если текущий поток не может изменить эту группу потоков.

См. также:

getMaxPriority

public final int getMaxPriority()

Возвращает максимальный приоритет этой группы потоков. Это максимальный приоритет для новых потоков, созданных в группе потоков.

Возвращает:

максимальный приоритет для новых потоков, созданных в группе потоков

См. также:

isDaemon

@Deprecated(since="16", forRemoval=true) public final boolean isDaemon()

Устаревший, подлежит удалению: Этот элемент API подлежит удалению в будущей версии.

Этот метод изначально показывал, является ли группа потоков группой потоков-демонов, которая автоматически уничтожается, когда завершается ее последний поток. Понятие группы потоков-демонов больше не существует. Группа потоков может быть удалена сборщиком мусора, когда в группе нет активных потоков и она не доступна по другим ссылкам.

Возвращает статус демона этой группы потоков. Статус демона ни для чего не используется.

Возвращает:: статус демона этой группы потоков

isDestroyed

@Deprecated(since="16", forRemoval=true) public boolean isDestroyed()

Устаревший, подлежит удалению: Этот элемент API подлежит удалению в будущей версии.

Этот метод изначально указывал, уничтожена ли группа потоков. Возможность уничтожить группу потоков и понятие уничтоженной группы потоков больше не существуют. Группа потоков может быть удалена сборщиком мусора, когда в группе нет активных потоков и она не доступна по другим ссылкам.

Возвращает false.

Возвращает:: false
С момента:: 1.1

setDaemon

@Deprecated(since="16", forRemoval=true) public final void setDaemon(boolean daemon)

Устаревший, подлежит удалению: Этот элемент API подлежит удалению в будущей версии.

Этот метод изначально настраивал, является ли группа потоков группой потоков-демонов, которая автоматически уничтожается, когда завершается ее последний поток. Понятие группы потоков-демонов больше не существует. Группа потоков может быть удалена сборщиком мусора, когда в группе нет активных потоков и она не доступна по другим ссылкам.

Устанавливает статус демона для этой группы потоков. Статус демона ни для чего не используется.

Сначала метод checkAccess этой группы потоков вызывается без аргументов; это может привести к исключению безопасности.

Параметры:

daemon - статус демона

Исключения:

SecurityException - если текущий поток не может изменить эту группу потоков.

См. также:

setMaxPriority

public final void setMaxPriority(int pri)

Устанавливает максимальный приоритет группы. Максимальный приоритет группы потоков для виртуальных потоков не изменяется этим методом (новый приоритет игнорируется). Потоки в группе потоков (или подгруппах), у которых уже выше приоритет, не затрагиваются этим методом.

Если аргумент pri меньше Thread.MIN_PRIORITY или больше Thread.MAX_PRIORITY, максимальный приоритет группы остается неизменным.

В противном случае приоритет этого объекта ThreadGroup устанавливается в меньшее из указанного pri и максимального разрешенного приоритета родителя этой группы потоков. (Если эта группа потоков является системной группой потоков, у которой нет родителя, то ее максимальный приоритет просто устанавливается в pri.) Затем этот метод вызывается рекурсивно с pri в качестве аргумента для каждой группы потоков, которая принадлежит этой группе потоков.

Параметры:

pri - новый приоритет группы потоков.

Исключения:

SecurityException - если текущий поток не может изменить эту группу потоков.

См. также:

parentOf

public final boolean parentOf(ThreadGroup g)

Проверяет, является ли эта группа потоков аргументом группы потоков или одной из ее предков-групп потоков.

Параметры:: g - группа потоков, может быть null
Возвращает:: true если эта группа потоков является аргументом группы потоков или одной из ее предков-групп потоков; false в противном случае.

checkAccess

@Deprecated(since="17", forRemoval=true) public final void checkAccess()

Устаревший, подлежит удалению: Этот элемент API подлежит удалению в будущей версии.

Этот метод полезен только в сочетании с Security Manager, который устарел и подлежит удалению в будущей версии. Следовательно, этот метод также устарел и подлежит удалению. Замены для Security Manager или этого метода нет.

Определяет, имеет ли текущий поток разрешение на изменение этой группы потоков.

Если существует менеджер безопасности, его метод checkAccess вызывается с этой группой потоков в качестве аргумента. Это может привести к исключению SecurityException.

Исключения:

SecurityException - если текущему потоку запрещен доступ к этой группе потоков.

См. также:

activeCount

public int activeCount()

Возвращает приблизительное количество активных потоков платформы в этой группе потоков и ее подгруппах. Виртуальные потоки не включаются в оценку. Этот метод рекурсивно итерирует все подгруппы в этой группе потоков.

Возвращаемое значение является лишь приближением, поскольку количество потоков может динамически изменяться во время прохода по внутренним структурам данных и может быть подвержено влиянию определенных системных потоков. Этот метод предназначен в первую очередь для отладки и мониторинга.

Возвращает:: приблизительное количество активных потоков в этой группе потоков и в любой другой группе потоков, у которой эта группа потоков является предком

enumerate

public int enumerate(Thread[] list)

Копирует в указанный массив каждый активный платформный поток в этой группе потоков и ее подгруппах. Виртуальные потоки этим методом не перечисляются.

Вызов этого метода ведет себя точно так же, как вызов

enumerate(list, true)

Параметры:: list - массив, в который нужно поместить список потоков
Возвращает:: количество потоков, помещенных в массив
Исключения:: SecurityException - если checkAccess определяет, что текущий поток не может получить доступ к этой группе потоков

enumerate

public int enumerate(Thread[] list, boolean recurse)

Копирует в указанный массив все активные платформенные потоки в этой группе потоков. Виртуальные потоки этим методом не перечисляются. Если recurse равно true, этот метод рекурсивно перечисляет все подгруппы этой группы потоков, и ссылки на все активные платформенные потоки в этих подгруппах также включаются. Если массив слишком короткий, чтобы вместить все потоки, дополнительные потоки игнорируются.

Приложение может использовать метод activeCount для оценки, каким должен быть размер массива, однако если массив слишком короткий, чтобы вместить все потоки, дополнительные потоки игнорируются. Если крайне важно получить все активные потоки в этой группе потоков, вызывающий метод должен проверить, что возвращаемое значение int строго меньше длины list.

Из-за внутренней гонки в этом методе рекомендуется использовать его только для отладки и мониторинга.

Parameters:: list - массив, в который нужно поместить список потоков; recurse - если true, рекурсивно перечислить все подгруппы этой группы потоков
Returns:: количество потоков, помещенных в массив
Throws:: SecurityException - если checkAccess определяет, что текущий поток не имеет доступа к этой группе потоков

activeGroupCount

public int activeGroupCount()

Возвращает приблизительное количество групп в этой группе потоков и ее подгруппах. Рекурсивно итерирует по всем подгруппам в этой группе потоков.

Возвращаемое значение является лишь приблизительным, поскольку количество групп потоков может динамически изменяться во время обхода внутренних структур данных. Этот метод предназначен в первую очередь для отладки и мониторинга.

Returns:: количество групп потоков, у которых эта группа потоков является предком

enumerate

public int enumerate(ThreadGroup[] list)

Копирует в указанный массив ссылки на все подгруппы в этой группе потоков и ее подгруппах.

Вызов этого метода ведет себя точно так же, как вызов

enumerate(list, true)

Parameters:: list - массив, в который нужно поместить список групп потоков
Returns:: количество групп потоков, помещенных в массив
Throws:: SecurityException - если checkAccess определяет, что текущий поток не имеет доступа к этой группе потоков

enumerate

public int enumerate(ThreadGroup[] list, boolean recurse)

Копирует в указанный массив ссылки на все подгруппы в этой группе потоков. Если recurse равно true, этот метод рекурсивно перечисляет все подгруппы этой группы потоков, и ссылки на все группы потоков в этих подгруппах также включаются.

Приложение может использовать метод activeGroupCount для оценки, каким должен быть размер массива, однако если массив слишком короткий, чтобы вместить все группы потоков, дополнительные группы потоков игнорируются. Если крайне важно получить все подгруппы в этой группе потоков, вызывающий метод должен проверить, что возвращаемое значение int строго меньше длины list.

Из-за внутренней гонки в этом методе рекомендуется использовать его только для отладки и мониторинга.

Parameters:: list - массив, в который нужно поместить список групп потоков; recurse - если true, рекурсивно перечислить все подгруппы
Returns:: количество групп потоков, помещенных в массив
Throws:: SecurityException - если checkAccess определяет, что текущий поток не имеет доступа к этой группе потоков

stop

@Deprecated(since="1.2", forRemoval=true) public final void stop()

Deprecated, for removal: Этот элемент API может быть удален в будущей версии.

Этот метод изначально был предназначен для остановки всех потоков в группе потоков. Он был небезопасным.

Выбрасывает UnsupportedOperationException.

interrupt

public final void interrupt()

Прерывает все активные платформенные потоки в этой группе потоков и ее подгруппах.

Throws:

SecurityException - если текущий поток не имеет разрешения на доступ к этой группе потоков или к каким-либо потокам в группе потоков.

Since:

1.2

See Also:

suspend

@Deprecated(since="1.2", forRemoval=true) public final void suspend()

Deprecated, for removal: Этот элемент API может быть удален в будущей версии.

Этот метод изначально был предназначен для приостановки всех потоков в группе потоков.

Выбрасывает UnsupportedOperationException.

resume

@Deprecated(since="1.2", forRemoval=true) public final void resume()

Deprecated, for removal: Этот элемент API может быть удален в будущей версии.

Этот метод изначально был предназначен для возобновления всех потоков в группе потоков.

Выбрасывает UnsupportedOperationException.

destroy

@Deprecated(since="16", forRemoval=true) public final void destroy()

Deprecated, for removal: Этот элемент API может быть удален в будущей версии.

Этот метод изначально был предназначен для удаления пустой группы потоков. Возможность явного удаления группы потоков больше не существует. Группа потоков может быть удалена сборщиком мусора, когда в ней нет активных потоков и она не достижима другими способами.

Ничего не делает.

list

public void list()

Выводит информацию об этой группе потоков в стандартный вывод. Этот метод полезен только для отладки.

uncaughtException

public void uncaughtException(Thread t, Throwable e)

Вызывается виртуальной машиной Java, когда поток в этой группе потоков завершается из-за необработанного исключения, и поток не имеет установленного обработчика необработанных исключений Thread.UncaughtExceptionHandler.

Метод uncaughtException класса ThreadGroup выполняет следующее:

Если у этой группы потоков есть родительская группа потоков, вызывается метод uncaughtException родительской группы с теми же двумя аргументами.
В противном случае, этот метод проверяет, установлен ли стандартный обработчик необработанных исключений, и если да, вызывается его метод uncaughtException с теми же двумя аргументами.
В противном случае выводится сообщение, содержащее имя потока, возвращаемое методом getName потока, и стек-трейс с помощью метода Throwable исключения в стандартный поток ошибок.

Приложения могут переопределять этот метод в подклассах ThreadGroup для предоставления альтернативной обработки необработанных исключений.

Specified by:: uncaughtException in interface Thread.UncaughtExceptionHandler
Parameters:: t - поток, который собирается выйти.; e - необработанное исключение.

toString

public String toString()

Возвращает строковое представление этой группы потоков.

Overrides:: toString в классе Object
Returns:: строковое представление этой группы потоков.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ThreadGroup.html