/ home / community / community.windows / 2.2.0 / module / win_wait_for_process

community.windows.win_wait_for_process (2.2.0) — module

Waits for a process to exist or not exist before continuing.

Authors: Charles Crossan (@crossan007)

Install collection

Install with ansible-galaxy collection install community.windows:==2.2.0

Add to requirements.yml

  collections:
    - name: community.windows
      version: 2.2.0

Description

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.

Usage examples

Scanned by Steampunk Spotter

- name: Wait 300 seconds for all Oracle VirtualBox processes to stop. (VBoxHeadless, VirtualBox, VBoxSVC)
  community.windows.win_wait_for_process:
    process_name_pattern: 'v(irtual)?box(headless|svc)?'
    state: absent
    timeout: 500

Scanned by Steampunk Spotter

- name: Wait 300 seconds for 3 instances of cmd to start, waiting 5 seconds between each check
  community.windows.win_wait_for_process:
    process_name_exact: cmd
    state: present
    timeout: 500
    sleep: 5
    process_min_count: 3

Inputs

pid:
default: 0
description:
- The PID of the process.
type: int

owner:
description:
- The owner of the process.
- Requires PowerShell version 4.0 or newer.
type: str

sleep:
default: 1
description:
- 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.
type: int

state:
choices:
- absent
- present
default: present
description:
- When checking for a running process C(present) will block execution until the process
exists, or until the timeout has been reached. C(absent) will block execution until
the process no longer exists, or until the timeout has been reached.
- When waiting for C(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 C(absent), new processes matching the supplied pattern are
started, these new processes will not be included in the action.
type: str

timeout:
default: 300
description:
- The maximum number of seconds to wait for a for a process to start or stop before
erroring out.
type: int

pre_wait_delay:
default: 0
description:
- Seconds to wait before checking processes.
type: int

post_wait_delay:
default: 0
description:
- Seconds to wait after checking for processes.
type: int

process_min_count:
default: 1
description:
- Minimum number of process matching the supplied pattern to satisfy C(present) condition.
- Only applies to C(present).
type: int

process_name_exact:
description:
- The name of the process(es) for which to wait. The name of the process(es) should
not include the file extension suffix.
elements: str
type: list

process_name_pattern:
description:
- RegEx pattern matching desired process(es).
type: str

Outputs

elapsed:
  description: The elapsed seconds between the start of poll and the end of the module.
  returned: always
  sample: 3.14159265
  type: float
matched_processes:
  contains:
    name:
      description: The name of the matched process.
      returned: always
      sample: svchost
      type: str
    owner:
      description: The owner of the matched process.
      returned: when supported by PowerShell
      sample: NT AUTHORITY\SYSTEM
      type: str
    pid:
      description: The PID of the matched process.
      returned: always
      sample: 7908
      type: int
  description: List of matched processes (either stopped or started).
  returned: always
  type: complex