ProcessUtil

public final class ProcessUtil
extends Object

java.lang.Object
   ↳ com.android.sts.common.ProcessUtil


Various helpers to find, wait, and kill processes on the device

Summary

Nested classes

class ProcessUtil.KillException

 

Constants

long PROCESS_POLL_PERIOD_MS

long PROCESS_WAIT_TIMEOUT_MS

Public methods

static Optional<IFileEntry> findFileLoadedByProcess(ITestDevice device, String process, String filenameSubstr)

Returns file entry of the first file loaded by the specified process with specified name

static Optional<List<String>> findFilesLoadedByProcess(ITestDevice device, int pid, Pattern filePattern)

Returns file names of the specified file, loaded by the specified process.

static Optional<String> getProcessName(ITestDevice device, int pid)

Get the contents from /proc/pid/cmdline.

static boolean killAll(ITestDevice device, String pgrepRegex, long timeoutMs, boolean expectExist)

Send SIGKILL to a all processes matching a pattern.

static boolean killAll(ITestDevice device, String pgrepRegex, long timeoutMs)

Send SIGKILL to a all processes matching a pattern.

static void killPid(ITestDevice device, int pid, long timeoutMs)

Send SIGKILL to a process and wait for it to be exited.

static void killPid(ITestDevice device, int pid, int signal, long timeoutMs)

Send a signal to a process and wait for it to be exited.

static Optional<List<String>> listOpenFiles(ITestDevice device, int pid)

Returns the currently open file names of the specified process.

static Optional<Integer> pidOf(ITestDevice device, String pgrepRegex)

Get a single pid matching a pattern passed to `pgrep`.

static Optional<Map<Integer, String>> pidsOf(ITestDevice device, String pgrepRegex)

Get the pids matching a pattern passed to `pgrep`.

static void waitPidExited(ITestDevice device, int pid)

Wait for a process to be exited.

static void waitPidExited(ITestDevice device, int pid, long timeoutMs)

Wait for a process to be exited.

static Map<Integer, String> waitProcessRunning(ITestDevice device, String pgrepRegex, long timeoutMs)

Wait until a running process is found for a given regex.

static Map<Integer, String> waitProcessRunning(ITestDevice device, String pgrepRegex)

Wait until a running process is found for a given regex.

static AutoCloseable withProcessKill(ITestDevice device, String pgrepRegex, Runnable beforeCloseKill, long timeoutMs)

Kill a process at the beginning and end of a test.

static AutoCloseable withProcessKill(ITestDevice device, String pgrepRegex, Runnable beforeCloseKill)

Kill a process at the beginning and end of a test.

Constants

PROCESS_POLL_PERIOD_MS

public static final long PROCESS_POLL_PERIOD_MS

Constant Value: 250 (0x00000000000000fa)

PROCESS_WAIT_TIMEOUT_MS

public static final long PROCESS_WAIT_TIMEOUT_MS

Constant Value: 10000 (0x0000000000002710)

Public methods

findFileLoadedByProcess

public static Optional<IFileEntry> findFileLoadedByProcess (ITestDevice device, 
                String process, 
                String filenameSubstr)

Returns file entry of the first file loaded by the specified process with specified name

Parameters
device ITestDevice: device to be run on

process String: pgrep pattern of process to look for

filenameSubstr String: part of file name/path loaded by the process

Returns
Optional<IFileEntry> an Opotional of IFileEntry of the path of the file on the device if exists.

Throws
DeviceNotAvailableException

findFilesLoadedByProcess

public static Optional<List<String>> findFilesLoadedByProcess (ITestDevice device, 
                int pid, 
                Pattern filePattern)

Returns file names of the specified file, loaded by the specified process.

Parameters
device ITestDevice: device to be run on

pid int: the id of the process to search

filePattern Pattern: a pattern of the file names to return

Returns
Optional<List<String>> an Optional of the filtered files; empty if the process wasn't found or the open files couldn't be read.

Throws
DeviceNotAvailableException

getProcessName

public static Optional<String> getProcessName (ITestDevice device, 
                int pid)

Get the contents from /proc/pid/cmdline.

Parameters
device ITestDevice: the device to use

pid int: the id of the process to get the name for

Returns
Optional<String> an Optional String of the contents of /proc/pid/cmdline; empty if the pid could not be found

Throws
DeviceNotAvailableException

killAll

public static boolean killAll (ITestDevice device, 
                String pgrepRegex, 
                long timeoutMs, 
                boolean expectExist)

Send SIGKILL to a all processes matching a pattern.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

timeoutMs long: how long to wait before throwing a TimeoutException

expectExist boolean: whether an exception should be thrown when no processes were killed

Returns
boolean whether any processes were killed

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException

killAll

public static boolean killAll (ITestDevice device, 
                String pgrepRegex, 
                long timeoutMs)

Send SIGKILL to a all processes matching a pattern.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

timeoutMs long: how long to wait before throwing a TimeoutException

Returns
boolean whether any processes were killed

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException

killPid

public static void killPid (ITestDevice device, 
                int pid, 
                long timeoutMs)

Send SIGKILL to a process and wait for it to be exited.

Parameters
device ITestDevice: the device to use

pid int: the id of the process to wait until exited

timeoutMs long: how long to wait before throwing a TimeoutException

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException

killPid

public static void killPid (ITestDevice device, 
                int pid, 
                int signal, 
                long timeoutMs)

Send a signal to a process and wait for it to be exited.

Parameters
device ITestDevice: the device to use

pid int: the id of the process to wait until exited

signal int: the signal to send to the process

timeoutMs long: how long to wait before throwing a TimeoutException

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException

listOpenFiles

public static Optional<List<String>> listOpenFiles (ITestDevice device, 
                int pid)

Returns the currently open file names of the specified process.

Parameters
device ITestDevice: device to be run on

pid int: the id of the process to search

Returns
Optional<List<String>> an Optional of the open files; empty if the process wasn't found or the open files couldn't be read.

Throws
DeviceNotAvailableException

pidOf

public static Optional<Integer> pidOf (ITestDevice device, 
                String pgrepRegex)

Get a single pid matching a pattern passed to `pgrep`. Throw an IllegalArgumentException when there are more than one PID matching the pattern.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

Returns
Optional<Integer> an Optional Integer of the pid; empty if pgrep did not return EXIT_SUCCESS

Throws
DeviceNotAvailableException
IllegalArgumentException

pidsOf

public static Optional<Map<Integer, String>> pidsOf (ITestDevice device, 
                String pgrepRegex)

Get the pids matching a pattern passed to `pgrep`. Because /proc/pid/comm is truncated, `pgrep` is passed with `-f` to check the full command line.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

Returns
Optional<Map<Integer, String>> an Optional Map of pid to command line; empty if pgrep did not return EXIT_SUCCESS

Throws
DeviceNotAvailableException

waitPidExited

public static void waitPidExited (ITestDevice device, 
                int pid)

Wait for a process to be exited. This is not waiting for it to change, but simply be nonexistent. It is possible, but unlikely, for a pid to be reused between polls

Parameters
device ITestDevice: the device to use

pid int: the id of the process to wait until exited

Throws
TimeoutException
DeviceNotAvailableException
ProcessUtil.KillException

waitPidExited

public static void waitPidExited (ITestDevice device, 
                int pid, 
                long timeoutMs)

Wait for a process to be exited. This is not waiting for it to change, but simply be nonexistent. It is possible, but unlikely, for a pid to be reused between polls

Parameters
device ITestDevice: the device to use

pid int: the id of the process to wait until exited

timeoutMs long: how long to wait before throwing a TimeoutException

Throws
TimeoutException
DeviceNotAvailableException
ProcessUtil.KillException

waitProcessRunning

public static Map<Integer, String> waitProcessRunning (ITestDevice device, 
                String pgrepRegex, 
                long timeoutMs)

Wait until a running process is found for a given regex.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

timeoutMs long: how long to wait before throwing a TimeoutException

Returns
Map<Integer, String> the pid to command map from pidsOf(...)

Throws
TimeoutException
DeviceNotAvailableException

waitProcessRunning

public static Map<Integer, String> waitProcessRunning (ITestDevice device, 
                String pgrepRegex)

Wait until a running process is found for a given regex.

Parameters
device ITestDevice: the device to use

pgrepRegex String: a String representing the regex for pgrep

Returns
Map<Integer, String> the pid to command map from pidsOf(...)

Throws
TimeoutException
DeviceNotAvailableException

withProcessKill

public static AutoCloseable withProcessKill (ITestDevice device, 
                String pgrepRegex, 
                Runnable beforeCloseKill, 
                long timeoutMs)

Kill a process at the beginning and end of a test.

Parameters
device ITestDevice: the device to use

pgrepRegex String: the name pattern of the process to kill to give to pgrep

beforeCloseKill Runnable: a runnable for any actions that need to cleanup before killing the process in a normal environment at the end of the test. Can be null.

timeoutMs long: how long in milliseconds to wait for the process to kill

Returns
AutoCloseable An object that will kill the process again when it is closed

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException

withProcessKill

public static AutoCloseable withProcessKill (ITestDevice device, 
                String pgrepRegex, 
                Runnable beforeCloseKill)

Kill a process at the beginning and end of a test.

Parameters
device ITestDevice: the device to use

pgrepRegex String: the name pattern of the process to kill to give to pgrep

beforeCloseKill Runnable: a runnable for any actions that need to cleanup before killing the process in a normal environment at the end of the test. Can be null.

Returns
AutoCloseable An object that will kill the process again when it is closed

Throws
DeviceNotAvailableException
TimeoutException
ProcessUtil.KillException