Интерфейс 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(), можно использовать для ожидания завершения процесса и, возможно, запуска зависимых действий.

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

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

pid

long pid()

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

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

of

static Optional<ProcessHandle> of(long pid)

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

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

current

static ProcessHandle current()

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

Возвращает:: ProcessHandle для текущего процесса
Исключение:: SecurityException - если установлен менеджер безопасности и он запрещает RuntimePermission("manageProcess"); UnsupportedOperationException - если реализация не поддерживает эту операцию

parent

Optional<ProcessHandle> parent()

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

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

children

Stream<ProcessHandle> children()

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

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

Возвращает:: последовательный Stream из ProcessHandles для процессов, являющихся непосредственными дочерними процессами
Исключение:: SecurityException - если установлен менеджер безопасности и он запрещает RuntimePermission("manageProcess")

descendants

Stream<ProcessHandle> descendants()

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

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

Возвращает:: последовательный Stream из ProcessHandles для процессов, являющихся потомками процесса
Исключение:: SecurityException - если установлен менеджер безопасности и он запрещает RuntimePermission("manageProcess")

allProcesses

static Stream<ProcessHandle> allProcesses()

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

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

Возвращает:: Stream из ProcessHandles для всех процессов
Исключение:: SecurityException - если установлен менеджер безопасности и он запрещает RuntimePermission("manageProcess"); UnsupportedOperationException - если реализация не поддерживает эту операцию

info

ProcessHandle.Info info()

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

Объект ProcessHandle.Info имеет методы доступа, которые возвращают информацию о процессе, если она доступна.

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

onExit

CompletableFuture<ProcessHandle> onExit()

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

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

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

Overrides:

hashCode в классе Object

Возвращает:

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

См. также:

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 имеют одинаковую реализацию и представляют один и тот же системный процесс. Сравнение поддерживается только для объектов одной реализации. Если попытка взаимного сравнения двух разных реализаций ProcessHandles, будет выброшено исключение ClassCastException.

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

© 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/ProcessHandle.html