Интерфейс ThreadReference

Все суперинтерфейсы:: Mirror, ObjectReference, Value

public interface ThreadReference extends ObjectReference

Объект потока из целевой виртуальной машины. ThreadReference — это ObjectReference с дополнительным доступом к информации о потоках целевой виртуальной машины.

Начиная с версии:: 1.3

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`THREAD_STATUS_MONITOR`	Поток ожидает освобождения монитора Java
`static final int`	`THREAD_STATUS_NOT_STARTED`	Поток ещё не запущен
`static final int`	`THREAD_STATUS_RUNNING`	Поток готов к выполнению
`static final int`	`THREAD_STATUS_SLEEPING`	Поток спит — `Thread.sleep(long)`.
`static final int`	`THREAD_STATUS_UNKNOWN`	Состояние потока неизвестно
`static final int`	`THREAD_STATUS_WAIT`	Поток ожидает — `Object.wait()` или `LockSupport.park()`.
`static final int`	`THREAD_STATUS_ZOMBIE`	Выполнение потока завершено

Поля, объявленные в интерфейсе ObjectReference

INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED

Модификатор и тип	Поле	Описание
`static final int`	`INVOKE_NONVIRTUAL`	Выполнить невиртуальный вызов метода
`static final int`	`INVOKE_SINGLE_THREADED`	Выполнить вызов метода, возобновив только вызывающий поток

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

Модификатор и тип	Метод	Описание
`ObjectReference`	`currentContendedMonitor()`	Возвращает `ObjectReference` монитора, если таковой имеется, которого в данный момент ожидает этот поток.
`void`	`forceEarlyReturn(Value value)`	Принудительно завершает метод до достижения оператора возврата.
`StackFrame`	`frame(int index)`	Возвращает `StackFrame` с указанным индексом в текущем стеке вызовов потока.
`int`	`frameCount()`	Возвращает количество кадров стека в текущем стеке вызовов потока.
`List<StackFrame>`	`frames()`	Возвращает список, содержащий каждый `StackFrame` из текущего стека вызовов потока.
`List<StackFrame>`	`frames(int start, int length)`	Возвращает список, содержащий диапазон зеркал `StackFrame` из текущего стека вызовов потока.
`void`	`interrupt()`	Прерывает этот поток, если только он не приостановлен отладчиком.
`boolean`	`isAtBreakpoint()`	Определяет, приостановлен ли поток в точке останова.
`boolean`	`isSuspended()`	Определяет, был ли поток приостановлен отладчиком.
`default boolean`	`isVirtual()`	Возвращает `true`, если поток является виртуальным потоком.
`String`	`name()`	Возвращает имя этого потока.
`List<ObjectReference>`	`ownedMonitors()`	Возвращает список, содержащий `ObjectReference` для каждого монитора, которым владеет поток.
`List<MonitorInfo>`	`ownedMonitorsAndFrames()`	Возвращает список, содержащий объект `MonitorInfo` для каждого монитора, которым владеет поток.
`void`	`popFrames(StackFrame frame)`	Извлекает кадры стека.
`void`	`resume()`	Возобновляет выполнение этого потока.
`int`	`status()`	Возвращает состояние потока.
`void`	`stop(ObjectReference throwable)`	Останавливает этот поток асинхронным исключением.
`void`	`suspend()`	Приостанавливает этот поток.
`int`	`suspendCount()`	Возвращает количество ожидающих приостановок этого потока.
`ThreadGroupReference`	`threadGroup()`	Возвращает группу потоков, к которой принадлежит этот поток.

Методы, объявленные в интерфейсе Mirror

toString, virtualMachine

Модификатор и тип	Метод	Описание
`String`	`toString()`	Возвращает строку с описанием этого зеркала
`VirtualMachine`	`virtualMachine()`	Возвращает VirtualMachine, к которой относится это зеркало.

Методы, объявленные в интерфейсе ObjectReference

disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads

Модификатор и тип	Метод	Описание
`void`	`disableCollection()`	Запрещает сборку мусора для этого объекта.
`void`	`enableCollection()`	Разрешает сборку мусора для этого объекта.
`int`	`entryCount()`	Возвращает количество раз, которое текущий поток-владелец входил в монитор этого объекта, если поток-владелец является потоком платформы; возвращает 0, если монитором не владеет поток платформы.
`boolean`	`equals(Object obj)`	Сравнивает указанный объект с этим ObjectReference на равенство.
`Value`	`getValue(Field sig)`	Возвращает значение заданного экземплярного или статического поля этого объекта.
`Map<Field,Value>`	`getValues(List<? extends Field> fields)`	Возвращает значения нескольких экземплярных и/или статических полей этого объекта.
`int`	`hashCode()`	Возвращает значение хеш-кода этого ObjectReference.
`Value`	`invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options)`	Вызывает указанный `Method` для этого объекта в целевой виртуальной машине.
`boolean`	`isCollected()`	Определяет, был ли этот объект удалён сборщиком мусора в целевой виртуальной машине.
`ThreadReference`	`owningThread()`	Возвращает `ThreadReference` потока платформы, если таковой имеется, который в данный момент владеет монитором этого объекта.
`ReferenceType`	`referenceType()`	Возвращает `ReferenceType`, соответствующее типу этого объекта.
`List<ObjectReference>`	`referringObjects(long maxReferrers)`	Возвращает объекты, которые непосредственно ссылаются на этот объект.
`void`	`setValue(Field field, Value value)`	Задаёт значение указанного экземплярного или статического поля этого объекта.
`long`	`uniqueID()`	Возвращает уникальный идентификатор этого ObjectReference.
`List<ThreadReference>`	`waitingThreads()`	Возвращает список, содержащий `ThreadReference` для каждого потока платформы, который в данный момент ожидает освобождения монитора этого объекта.

Методы, объявленные в интерфейсе Value

type

Модификатор и тип	Метод	Описание
`Type`	`type()`	Возвращает тип этого значения во время выполнения.

Подробное описание полей

THREAD_STATUS_UNKNOWN

static final int THREAD_STATUS_UNKNOWN

Статус потока неизвестен

См. также:

THREAD_STATUS_ZOMBIE

static final int THREAD_STATUS_ZOMBIE

Выполнение потока завершено

См. также:

THREAD_STATUS_RUNNING

static final int THREAD_STATUS_RUNNING

Поток готов к выполнению

См. также:

THREAD_STATUS_SLEEPING

static final int THREAD_STATUS_SLEEPING

Поток спит — Thread.sleep(long).

См. также:

THREAD_STATUS_MONITOR

static final int THREAD_STATUS_MONITOR

Поток ожидает освобождения монитора Java

См. также:

THREAD_STATUS_WAIT

static final int THREAD_STATUS_WAIT

Поток ожидает — Object.wait() или LockSupport.park(). Виртуальный поток, ожидающий в Thread.sleep(long), может иметь этот статус вместо THREAD_STATUS_SLEEPING.

См. также:

THREAD_STATUS_NOT_STARTED

static final int THREAD_STATUS_NOT_STARTED

Поток еще не был запущен

См. также:

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

name

String name()

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

Возвращает:: строку, содержащую имя потока.

suspend

void suspend()

Приостанавливает этот поток. Возобновить выполнение потока можно с помощью resume() или вместе с другими потоками с помощью VirtualMachine.resume().

Приостановки виртуальной машины и отдельных потоков учитываются. Чтобы поток снова начал выполняться, его необходимо возобновить (с помощью resume() или VirtualMachine.resume()) столько же раз, сколько он был приостановлен.

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

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

Выбрасывает:

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения

См. также:

resume

void resume()

Возобновляет выполнение этого потока. Если этот поток ранее не был приостановлен с помощью suspend() или VirtualMachine.suspend(), а также не был приостановлен из-за события SUSPEND_ALL или SUSPEND_EVENT_THREAD, вызов этого метода не имеет эффекта. В противном случае счетчик ожидающих возобновления приостановок этого потока уменьшается. Если его значение становится равным 0, поток продолжает выполнение. Примечание: обычный способ возобновить выполнение после приостановки, связанной с событием, — использовать EventSet.resume().

Выбрасывает:

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения

См. также:

suspendCount

int suspendCount()

Возвращает количество ожидающих возобновления приостановок этого потока. Пояснение учета приостановок см. в описании suspend().

Возвращает:: количество ожидающих возобновления приостановок в виде целого числа

stop

void stop(ObjectReference throwable) throws InvalidTypeException

Останавливает этот поток асинхронным исключением. Поток отладчика в целевой виртуальной машине остановит этот поток, передав указанный объект Throwable.

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

Параметры:

throwable — асинхронное исключение, которое необходимо выбросить

Выбрасывает:

InvalidTypeException — если throwable не является экземпляром java.lang.Throwable в целевой виртуальной машине

IllegalThreadStateException — если выполнение потока завершено или если поток является виртуальным и не был приостановлен

OpaqueFrameException — если поток является приостановленным виртуальным потоком, а реализация не смогла выбросить асинхронное исключение из текущего кадра потока

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения

См. также:

interrupt

void interrupt()

Прерывает этот поток, если только он не был приостановлен отладчиком.

Выбрасывает:

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения

См. также:

status

int status()

Возвращает статус потока. Если поток не приостановлен, возвращается его текущий статус. Если поток приостановлен, возвращается статус, который у него был до приостановки (или THREAD_STATUS_UNKNOWN, если эта информация недоступна). Чтобы определить, был ли поток приостановлен, можно использовать isSuspended().

Возвращает:: одно из значений THREAD_STATUS_UNKNOWN, THREAD_STATUS_ZOMBIE, THREAD_STATUS_RUNNING, THREAD_STATUS_SLEEPING, THREAD_STATUS_MONITOR, THREAD_STATUS_WAIT, THREAD_STATUS_NOT_STARTED,

isSuspended

boolean isSuspended()

Определяет, был ли поток приостановлен отладчиком.

Возвращает:: true, если поток в данный момент приостановлен; в противном случае — false.

isAtBreakpoint

boolean isAtBreakpoint()

Определяет, приостановлен ли поток на точке останова.

Возвращает:: true, если поток в данный момент остановлен на точке останова; в противном случае — false.

threadGroup

ThreadGroupReference threadGroup()

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

Возвращает:: объект ThreadGroupReference, представляющий группу потоков этого потока в целевой виртуальной машине.

frameCount

int frameCount() throws IncompatibleThreadStateException

Возвращает количество кадров стека в текущем стеке вызовов потока. Чтобы получить эту информацию, поток должен быть приостановлен (обычно из-за прерывания виртуальной машины); она действительна только до возобновления выполнения потока.

Возвращает:: количество кадров в виде целого числа
Выбрасывает:: IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине

frames

List<StackFrame> frames() throws IncompatibleThreadStateException

Возвращает List, содержащий каждый StackFrame из текущего стека вызовов потока. Чтобы получить эту информацию, поток должен быть приостановлен (обычно из-за прерывания виртуальной машины); она действительна только до возобновления выполнения потока.

Возвращает:: List объектов StackFrame: сначала текущий кадр, затем кадры вызывающих методов.
Выбрасывает:: IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине

frame

StackFrame frame(int index) throws IncompatibleThreadStateException

Возвращает StackFrame с указанным индексом в текущем стеке вызовов потока. Индекс 0 соответствует текущему кадру; большие индексы соответствуют кадрам вызывающих методов. Чтобы получить эту информацию, поток должен быть приостановлен (обычно из-за прерывания виртуальной машины); она действительна только до возобновления выполнения потока.

Параметры:: index — требуемый кадр
Возвращает:: запрошенный StackFrame
Выбрасывает:: IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине; IndexOutOfBoundsException — если индекс больше или равен frameCount() либо отрицателен.

frames

List<StackFrame> frames(int start, int length) throws IncompatibleThreadStateException

Возвращает List, содержащий диапазон объектов StackFrame, представляющих кадры текущего стека вызовов потока. Чтобы получить эту информацию, поток должен быть приостановлен (обычно из-за прерывания виртуальной машины); она действительна только до возобновления выполнения потока.

Параметры:

start — индекс первого кадра, который необходимо получить. Индекс 0 соответствует текущему кадру.

length — количество кадров, которые необходимо получить

Возвращает:

List объектов StackFrame: сначала текущий кадр, затем кадры вызывающих методов.

Выбрасывает:

IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине

IndexOutOfBoundsException — если указанный диапазон выходит за пределы диапазона индексов кадров стека. Иными словами, исключение выбрасывается, если выполняется хотя бы одно из следующих условий:

    start < 0
   start >= frameCount()
   length < 0
   (start+length) > frameCount()

ownedMonitors

List<ObjectReference> ownedMonitors() throws IncompatibleThreadStateException

Возвращает List, содержащий объект ObjectReference для каждого монитора, принадлежащего потоку. Монитор принадлежит потоку, если поток вошел в него (с помощью оператора synchronized или вызова синхронизированного метода) и не освободил его посредством Object.wait().

Не все целевые виртуальные машины поддерживают эту операцию. Чтобы определить, поддерживается ли она, используйте VirtualMachine.canGetOwnedMonitorInfo().

Возвращает:: List объектов ObjectReference. Список пуст, если этому потоку не принадлежат мониторы.
Выбрасывает:: UnsupportedOperationException — если целевая виртуальная машина не поддерживает эту операцию.; IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине

ownedMonitorsAndFrames

List<MonitorInfo> ownedMonitorsAndFrames() throws IncompatibleThreadStateException

Возвращает List, содержащий объект MonitorInfo для каждого монитора, принадлежащего потоку. Монитор принадлежит потоку, если поток вошел в него (с помощью оператора synchronized или вызова синхронизированного метода) и не освободил его посредством Object.wait().

Не все целевые виртуальные машины поддерживают эту операцию. Чтобы определить, поддерживается ли она, используйте VirtualMachine.canGetMonitorFrameInfo().

Возвращает:: List объектов MonitorInfo. Список пуст, если этому потоку не принадлежат мониторы.
Выбрасывает:: UnsupportedOperationException — если целевая виртуальная машина не поддерживает эту операцию.; IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине
Начиная с версии:: 1.6

currentContendedMonitor

ObjectReference currentContendedMonitor() throws IncompatibleThreadStateException

Возвращает объект ObjectReference монитора, если таковой имеется, которого в данный момент ожидает этот поток. Поток может ожидать монитор при входе в синхронизированный метод, выполнении оператора synchronized или вызове Object.wait(), ожидая повторного входа в монитор после уведомления, прерывания или истечения времени ожидания.

Не все целевые виртуальные машины поддерживают эту операцию. Чтобы определить, поддерживается ли она, используйте VirtualMachine.canGetCurrentContendedMonitor().

Возвращает:: объект ObjectReference, соответствующий монитору, которого ожидает поток, или null, если поток не ожидает монитор.
Выбрасывает:: UnsupportedOperationException — если целевая виртуальная машина не поддерживает эту операцию.; IncompatibleThreadStateException — если поток не приостановлен в целевой виртуальной машине

popFrames

void popFrames(StackFrame frame) throws IncompatibleThreadStateException

Удаляет кадры из стека.

Из стека удаляются все кадры вплоть до frame включительно. Кадр, предшествующий параметру frame, становится текущим кадром.

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

Стек операндов восстанавливается, однако изменения аргументов, произошедшие в вызванном методе, сохраняются. Например, если метод foo:

   void foo(int x) {
       System.out.println("Foo: " + x);
       x = 4;
       System.out.println("pop here");
   }

был вызван с foo(7), а foo удален при втором println и выполнение возобновлено, будет выведено: Foo: 4.

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

Блоки finally не выполняются.

Этот вызов влияет только на точку выполнения потока и блокировки; остальные аспекты состояния не затрагиваются. В частности, значения полей не изменяются, как и внешние ресурсы, например потоки ввода-вывода. Кроме того, целевая программа может оказаться в состоянии, невозможном при обычном ходе выполнения; например, может измениться порядок захвата блокировок. Поэтому целевая программа может продолжить работу не так, как ожидает пользователь.

Этот поток должен быть приостановлен.

Все объекты StackFrame этого потока становятся недействительными.

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

Этот метод не генерирует событий.

Ни один из кадров вплоть до кадра вызывающего метода для frame включительно не может быть нативным.

Не все целевые виртуальные машины поддерживают эту операцию. Чтобы определить, поддерживается ли она, используйте VirtualMachine.canPopFrames().

Параметры:

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

Выбрасывает:

UnsupportedOperationException — если целевая виртуальная машина не поддерживает эту операцию; см. VirtualMachine.canPopFrames().

IncompatibleThreadStateException — если этот поток не приостановлен.

IllegalArgumentException — если frame отсутствует в стеке вызовов этого потока.

OpaqueFrameException — если целевая виртуальная машина не может удалить этот кадр (например, виртуальный поток приостановлен, но не на событии).

NativeMethodException — если один из удаляемых кадров принадлежит нативному методу или кадр, предшествующий frame, является нативным.

InvalidStackFrameException — если frame стал недействительным. После возобновления потока кадр стека становится недействительным. Это исключение также выбрасывается, если кадров больше нет.

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения.

Начиная с версии:

1.4

См. также:

forceEarlyReturn

void forceEarlyReturn(Value value) throws InvalidTypeException, ClassNotLoadedException, IncompatibleThreadStateException

Принудительно завершает метод до достижения оператора return.

Метод, выполнение которого будет завершено досрочно, далее называется вызываемым методом. На момент вызова этого метода вызываемый метод является текущим методом (в соответствии с разделом «Кадры» спецификации виртуальной машины Java) для указанного потока.

Поток должен быть приостановлен. Возврат произойдет, когда выполнение кода на языке программирования Java в этом потоке будет возобновлено. Состояние стека в промежутке между вызовом этого метода и возобновлением выполнения потока не определено.

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

Дальнейшие инструкции вызываемого метода не выполняются. В частности, блоки finally не выполняются. Примечание: это может привести к несогласованному состоянию приложения.

Блокировка, полученная при вызове вызываемого метода (если он синхронизированный), и блокировки, полученные при входе в синхронизированные блоки внутри вызываемого метода, освобождаются. Примечание: это не относится к нативным блокировкам и блокировкам java.util.concurrent.locks.

События, например MethodExit, генерируются так же, как при обычном возврате.

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

Аргумент value — это значение, которое должен вернуть метод. Если тип возвращаемого значения метода — void, значение должно быть объектом VoidValue. Значения объектов должны быть совместимы по присваиванию с типом возвращаемого значения метода (это означает, что тип возвращаемого значения метода должен быть загружен загрузчиком классов, содержащим внешний класс). Примитивные значения должны быть совместимы по присваиванию с типом возвращаемого значения метода либо приводимы к типу переменной без потери информации. Дополнительные сведения о совместимости по присваиванию см. в разделе 5.2 JLS.

Не все целевые виртуальные машины поддерживают эту операцию. Чтобы определить, поддерживается ли она, используйте VirtualMachine.canForceEarlyReturn().

Параметры:

value — значение, которое должен вернуть метод.

Выбрасывает:

UnsupportedOperationException — если целевая виртуальная машина не поддерживает эту операцию; см. canForceEarlyReturn()

IncompatibleThreadStateException — если этот поток не приостановлен.

OpaqueFrameException — если целевая виртуальная машина не может принудительно завершить метод (например, виртуальный поток приостановлен, но не на событии).

NativeMethodException — если кадр, из которого выполняется возврат, принадлежит нативному методу.

InvalidStackFrameException — если кадров нет.

InvalidTypeException — если тип значения не соответствует типу возвращаемого значения метода.

ClassNotLoadedException — если тип возвращаемого значения метода еще не загружен подходящим загрузчиком классов.

VMCannotBeModifiedException — если VirtualMachine доступна только для чтения.

Начиная с версии:

1.6

См. также:

isVirtual

default boolean isVirtual()

Возвращает true, если поток является виртуальным потоком.

Требования к реализации:: Реализация по умолчанию выбрасывает UnsupportedOperationException.
Возвращает:: true, если поток является виртуальным
Начиная с версии:: 21

© 1993, 2025, 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.