Интерфейс 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 статические фабричные методы возвращают экземпляры, основанные на значениях, неизменяемые и безопасные для использования в многопоточной среде. Программистам следует считать взаимозаменяемыми экземпляры, которые равны, и не использовать экземпляры для синхронизации, иначе поведение может быть непредсказуемым. Например, в будущей версии синхронизация может завершиться неудачей. Для сравнения ProcessHandles используйте методы equals или compareTo.

С:

См. также:

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

Модификатор и тип	Интерфейс	Описание
`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)`	Возвращает `Optional<ProcessHandle>` для существующего нативного процесса.
`CompletableFuture<ProcessHandle>`	`onExit()`	Возвращает `CompletableFuture<ProcessHandle>` для завершения процесса.
`Optional<ProcessHandle>`	`parent()`	Возвращает `Optional<ProcessHandle>` для родительского процесса.
`long`	`pid()`	Возвращает идентификатор нативного процесса.
`boolean`	`supportsNormalTermination()`	Возвращает `true`, если реализация метода `destroy()` выполняет обычное завершение процесса.

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

pid

long pid()

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

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

of

static Optional<ProcessHandle> of(long pid)

Возвращает Optional<ProcessHandle> для существующего нативного процесса.

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

current

static ProcessHandle current()

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

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

parent

Optional<ProcessHandle> parent()

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

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

children

Stream<ProcessHandle> children()

Возвращает снимок текущих непосредственных дочерних процессов данного процесса. parent() непосредственного дочернего процесса является этот процесс. Как правило, у процесса, который 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<ProcessHandle> для завершения процесса. CompletableFuture позволяет запускать зависимые функции или действия синхронно либо асинхронно после завершения процесса. После завершения процесса CompletableFuture completed независимо от кода завершения процесса. Метод onExit можно вызывать несколько раз, чтобы запускать независимые действия при завершении процесса.

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

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

supportsNormalTermination

boolean supportsNormalTermination()

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

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

destroy

boolean destroy()

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

Объект 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() и может зависеть от дополнительных сведений, позволяющих однозначно идентифицировать процесс. Если согласно методу equals два ProcessHandle равны, то вызов метода hashCode для каждого из этих объектов должен возвращать одно и то же целое число.

Переопределяет:

hashCode в классе Object

Возвращает:

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

См. также:

equals

boolean equals(Object other)

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

Переопределяет:

equals в классе Object

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

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

Параметры:

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

Возвращает:

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

См. также:

compareTo

int compareTo(ProcessHandle other)

Сравнивает этот ProcessHandle с указанным ProcessHandle для определения порядка. Порядок не специфицирован, но согласован с методом Object.equals(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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/ProcessHandle.html