win_wait_for_process – Waits for a process to exist or not exist before continuing¶
New in version 2.7.
Synopsis¶
Waiting for a process to start or stop.
This is useful when Windows services behave poorly and do not enumerate external dependencies in their manifest.
Parameters¶
| Parameter | Choices/Defaults | Comments |
|---|---|---|
|
owner
string
|
The owner of the process.
Requires PowerShell version 4.0 or newer.
|
|
|
pid
integer
|
The PID of the process.
|
|
|
post_wait_delay
integer
|
Default: 0
|
Seconds to wait after checking for processes.
|
|
pre_wait_delay
integer
|
Default: 0
|
Seconds to wait before checking processes.
|
|
process_min_count
integer
|
Default: 1
|
Minimum number of process matching the supplied pattern to satisfy
present condition.Only applies to
present. |
|
process_name_exact
list
|
The name of the process(es) for which to wait.
|
|
|
process_name_pattern
string
|
RegEx pattern matching desired process(es).
|
|
|
sleep
integer
|
Default: 1
|
Number of seconds to sleep between checks.
Only applies when waiting for a process to start. Waiting for a process to start does not have a native non-polling mechanism. Waiting for a stop uses native PowerShell and does not require polling.
|
|
state
string
|
|
When checking for a running process
present will block execution until the process exists, or until the timeout has been reached. absent will block execution until the process no longer exists, or until the timeout has been reached.When waiting for
present, the module will return changed only if the process was not present on the initial check but became present on subsequent checks.If, while waiting for
absent, new processes matching the supplied pattern are started, these new processes will not be included in the action. |
|
timeout
integer
|
Default: 300
|
The maximum number of seconds to wait for a for a process to start or stop before erroring out.
|
See Also¶
See also
- wait_for – Waits for a condition before continuing
The official documentation on the wait_for module.
- win_wait_for – Waits for a condition before continuing
The official documentation on the win_wait_for module.
Examples¶
- name: Wait 300 seconds for all Oracle VirtualBox processes to stop. (VBoxHeadless, VirtualBox, VBoxSVC)
win_wait_for_process:
process_name_pattern: 'v(irtual)?box(headless|svc)?'
state: absent
timeout: 500
- name: Wait 300 seconds for 3 instances of cmd to start, waiting 5 seconds between each check
win_wait_for_process:
process_name_exact: cmd
state: present
timeout: 500
sleep: 5
process_min_count: 3
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description | |
|---|---|---|---|
|
elapsed
float
|
always |
The elapsed seconds between the start of poll and the end of the module.
Sample:
3.14159265
|
|
|
matched_processes
complex
|
always |
List of matched processes (either stopped or started).
|
|
|
name
string
|
always |
The name of the matched process.
Sample:
svchost
|
|
|
owner
string
|
when supported by PowerShell |
The owner of the matched process.
Sample:
NT AUTHORITY\SYSTEM
|
|
|
pid
integer
|
always |
The PID of the matched process.
Sample:
7908
|
|
Status¶
This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Community. [community]