Интерфейс ProcessHandle

Все суперинтерфейсы:: Comparable<ProcessHandle>

public interface ProcessHandle extends Comparable<ProcessHandle>

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

Идентификатор нативного процесса — это числовой идентификатор, который операционная система присваивает процессу. Диапазон значений идентификатора процесса зависит от операционной системы. Например, встраиваемая система может использовать 16-битовое значение. Информация о статусе процесса извлекается из нативной системы и может изменяться асинхронно; процессы могут создаваться или завершаться спонтанно. Время между завершением процесса и повторным использованием идентификатора процесса для нового процесса непредсказуемо. Могут существовать проблемы гонок при проверке статуса процесса и действиях по нему. При использовании ProcessHandles следует избегать предположений об активности или идентичности основного процесса.

Каждый ProcessHandle идентифицирует и разрешает управление процессом в нативной системе. ProcessHandles возвращаются методами-фабриками current(), of(long), children(), descendants(), parent() и allProcesses().

Экземпляры Process, созданные с помощью ProcessBuilder, могут быть запрошены для получения ProcessHandle, предоставляющего информацию о процессе. Ссылки на ProcessHandle не следует свободно распространять.

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

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

Требования к реализации:

В случае, когда ProcessHandles не могут быть поддерживаемы, методы-фабрики должны последовательно выбрасывать UnsupportedOperationException. Методы этого класса выбрасывают UnsupportedOperationException, если операционная система не разрешает доступ к запросу или завершению процесса.

Статические методы-фабрики ProcessHandle возвращают экземпляры, которые являются базовыми по значению, неизменяемыми и потокобезопасными. Программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, так как это может привести к непредсказуемому поведению. Например, в будущей версии синхронизация может не сработать. Используйте метод equals или compareTo для сравнения ProcessHandles.

С:

См. также:

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static interface`	`ProcessHandle.Info`	Снимок информации о процессе.

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

Модификатор и тип	Метод	Описание
`static Stream<ProcessHandle>`	`allProcesses()`	Возвращает снимок всех процессов, видимых текущему процессу.
`Stream<ProcessHandle>`	`children()`	Возвращает снимок всех непосредственных дочерних процессов.
`int`	`compareTo(ProcessHandle other)`	Сравнивает этот ProcessHandle с указанным ProcessHandle для определения порядка.
`static ProcessHandle`	`current()`	Возвращает ProcessHandle для текущего процесса.
`Stream<ProcessHandle>`	`descendants()`	Возвращает снимок потомков процесса.
`boolean`	`destroy()`	Запрашивает завершение процесса.
`boolean`	`destroyForcibly()`	Запрашивает принудительное завершение процесса.
`boolean`	`equals(Object other)`	Возвращает `true`, если объект `other` не null, имеет ту же реализацию и представляет тот же системный процесс; в противном случае возвращает `false`.
`int`	`hashCode()`	Возвращает хэш-код для этого ProcessHandle.
`ProcessHandle.Info`	`info()`	Возвращает снимок информации о процессе.
`boolean`	`isAlive()`	Проверяет, жив ли процесс, представленный этим `ProcessHandle`.
`static Optional<ProcessHandle>`	`of(long pid)`	Возвращает ProcessHandle для существующего нативного процесса.
`CompletableFuture<ProcessHandle>`	`onExit()`	Возвращает CompletableFuture для завершения процесса.
`Optional<ProcessHandle>`	`parent()`	Возвращает ProcessHandle для родительского процесса.
`long`	`pid()`	Возвращает идентификатор нативного процесса.
`boolean`	`supportsNormalTermination()`	Возвращает `true`, если реализация `destroy()` обычно завершает процесс.

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

pid

long pid()

Возвращает идентификатор процесса (PID) в системе. Идентификатор процесса — это число, которое операционная система присваивает процессу. Операционная система может повторно использовать идентификатор процесса после завершения процесса. Для сравнения ProcessHandle используйте методы equals или compareTo.

Возвращает:: идентификатор процесса (PID)
Исключения:: UnsupportedOperationException — если реализация не поддерживает эту операцию

of

static Optional<ProcessHandle> of(long pid)

Возвращает объект ProcessHandle для существующего процесса по его PID.

Параметры:: pid — идентификатор процесса (PID)
Возвращает:: объект ProcessHandle для заданного PID; если процесса с данным PID нет, возвращается пустой объект
Исключения:: UnsupportedOperationException — если реализация не поддерживает эту операцию

current

static ProcessHandle current()

Возвращает ProcessHandle для текущего процесса. ProcessHandle нельзя использовать для завершения текущего процесса; используйте System.exit вместо этого.

Возвращает:: ProcessHandle для текущего процесса
Исключения:: UnsupportedOperationException — если реализация не поддерживает эту операцию

parent

Optional<ProcessHandle> parent()

Возвращает ProcessHandle для родительского процесса. Обратите внимание, что процессы в состоянии "зомби" обычно не имеют родительского процесса.

Возвращает:: ProcessHandle родительского процесса; если у процесса нет родителя или родитель недоступен (возможно, из-за ограничений операционной системы), возвращается пустой объект

children

Stream<ProcessHandle> children()

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

Обратите внимание, что процессы создаются и завершаются асинхронно. Нет гарантии, что процесс alive.

Возвращает:: последовательную Stream объектов ProcessHandle для прямых дочерних процессов

descendants

Stream<ProcessHandle> descendants()

Возвращает моментальный снимок всех потомков процесса. Потомки процесса — это его дочерние процессы плюс потомки этих дочерних процессов (рекурсивно). Обычно у процесса, который not alive, нет дочерних процессов.

Обратите внимание, что процессы создаются и завершаются асинхронно. Нет гарантии, что процесс alive.

Возвращает:: последовательную Stream объектов ProcessHandle для всех потомков процесса

allProcesses

static Stream<ProcessHandle> allProcesses()

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

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

Возвращает:: Stream объектов ProcessHandle для всех процессов
Исключения:: UnsupportedOperationException — если реализация не поддерживает эту операцию

info

ProcessHandle.Info info()

Возвращает моментальный снимок информации о процессе.

Экземпляр интерфейса ProcessHandle.Info содержит методы доступа к информации о процессе, если она доступна.

Возвращает:: моментальный снимок информации о процессе (всегда не null)

onExit

CompletableFuture<ProcessHandle> onExit()

Возвращает объект CompletableFuture для обработки завершения процесса. CompletableFuture позволяет выполнить зависимые функции или действия синхронно или асинхронно при завершении процесса. При завершении процесса CompletableFuture устанавливается в завершённое состояние completed, независимо от кода возврата процесса. Метод onExit можно вызывать несколько раз для выполнения независимых действий при выходе процесса.

Вызов onExit().get() ожидает завершения процесса и возвращает ProcessHandle. Future можно использовать для проверки, завершён ли процесс done, или для получения результата завершения wait. Отмена Cancelling CompletableFuture не влияет на процесс.

Примечание API:: Процесс может показаться завершённым с помощью isAlive() до завершения ComputableFuture и выполнения зависимых действий.
Возвращает:: новый CompletableFuture для ProcessHandle
Исключения:: IllegalStateException — если процесс — текущий процесс

supportsNormalTermination

boolean supportsNormalTermination()

Возвращает true, если реализация метода destroy() завершает процесс нормально. Возвращает false, если реализация метода destroy завершает процесс принудительно и немедленно.

Возвращает:: true, если реализация destroy() завершает процесс нормально; в противном случае destroy() завершает процесс принудительно

destroy

boolean destroy()

Запрос на завершение процесса. Способ завершения процесса (нормально или принудительно) зависит от реализации. Принудительное завершение означает немедленное завершение процесса, а нормальное завершение позволяет процессу завершиться корректно. Если процесс не активен, никаких действий не выполняется. Возможно, доступ операционной системы может предотвратить завершение процесса.

CompletableFuture из onExit() устанавливается в завершённое состояние completed при завершении процесса.

Примечание: Процесс может не завершиться немедленно. Например, isAlive() может возвращать true в течение короткого времени после вызова destroy().

Возвращает:: true, если запрос на завершение был успешно выполнен; в противном случае false
Исключения:: IllegalStateException — если процесс — текущий процесс

destroyForcibly

boolean destroyForcibly()

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

CompletableFuture из onExit() устанавливается в завершённое состояние completed при завершении процесса.

Примечание: Процесс может не завершиться немедленно. Например, isAlive() может возвращать true в течение короткого времени после вызова destroyForcibly().

Возвращает:: true, если запрос на завершение был успешно выполнен; в противном случае false
Исключения:: IllegalStateException — если процесс — текущий процесс

isAlive

boolean isAlive()

Проверяет, жив ли процесс, представленный этим объектом ProcessHandle. Завершение процесса зависит от реализации и операционной системы. Процесс считается живым, пока действителен его PID.

Возвращает:: true, если процесс, представленный этим объектом ProcessHandle, ещё не завершён

hashCode

int hashCode()

Возвращает значение хэш-кода для данного ProcessHandle. Значение хэш-кода следует общему соглашению для Object.hashCode(). Значение является функцией от значения pid() и может зависеть от дополнительной информации для уникальной идентификации процесса. Если два ProcessHandle равны в соответствии с методом equals, то вызов метода hashCode для каждого из этих двух объектов должен возвращать одно и то же целое значение.

Overrides:

hashCode в классе Object

Returns:

значение хэш-кода для данного объекта

См. также:

equals

boolean equals(Object other)

Возвращает true, если объект other не null, имеет ту же реализацию и представляет тот же системный процесс; в противном случае возвращает false.

Overrides:

equals в классе Object

Примечание по реализации:

Зависит от реализации, представляют ли ProcessHandle с одинаковым PID тот же системный процесс. Реализации ProcessHandle должны содержать дополнительную информацию для уникальной идентификации процесса. Например, время запуска процесса можно использовать для определения, был ли PID повторно использован. Реализация equals должна возвращать true для двух ProcessHandle с одинаковым PID, если нет информации для их различения.

Параметры:

other - другой объект

Возвращает:

true, если объект other не null, принадлежит тому же классу реализации и представляет тот же системный процесс; в противном случае возвращает false

См. также:

compareTo

int compareTo(ProcessHandle other)

Сравнивает этот ProcessHandle с указанным ProcessHandle для определения порядка. Порядок не задан, но согласуется с Object.equals(java.lang.Object), который возвращает true тогда и только тогда, когда два экземпляра ProcessHandle имеют одинаковую реализацию и представляют один и тот же системный процесс. Сравнение поддерживается только для объектов одной реализации. Если производится попытка взаимного сравнения двух различных реализаций ProcessHandle, выбрасывается ClassCastException.

Определено в:: compareTo в интерфейсе Comparable<ProcessHandle>
Параметры:: other - ProcessHandle для сравнения
Возвращает:: отрицательное целое число, ноль или положительное целое число, в зависимости от того, меньше, равно или больше, чем заданный объект.
Исключение:: NullPointerException - если указанный объект null; ClassCastException - если указанный объект не принадлежит тому же классу, что и этот объект

© 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.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/lang/ProcessHandle.html