Интерфейс 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.

С:

См. также:

Process

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

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

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

pid

long pid()

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

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

of

static Optional<ProcessHandle> of(long pid)

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

Параметры:: pid - идентификатор процесса (native process ID)
Возвращает:: ProcessHandle, соответствующий указанному идентификатору процесса; 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() прямого дочернего процесса — это сам процесс. Как правило, у работающего процесса нет дочерних процессов.

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

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

descendants

Stream<ProcessHandle> descendants()

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

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

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

allProcesses

static Stream<ProcessHandle> allProcesses()

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

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

Возвращает:: поток 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()

Запрос на уничтожение процесса. Зависит от реализации, завершает ли процесс представленный этим объектом 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 если переданный объект не равен null, имеет тот же класс реализации и представляет тот же системный процесс; в противном случае возвращает false.

Overrides:

equals в классе Object

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

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

Параметры:

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

Возвращает:

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

См. также:

compareTo

int compareTo(ProcessHandle other)

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

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

© 1993, 2021, 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/17/docs/api/java.base/java/lang/ProcessHandle.html