Shutdown & Teardown

Table of Contents

1. OS Shutdown Handling (v6.2+)
2. The Shutdown Sequence
3. Key Features
4. Mandatory Reinstallation
5. Extending the Shutdown Window
6. Notes

OS Shutdown Handling (v6.2+)

Servy v6.2+ introduces high reliability service teardown during operating system shutdown and reboot, matching the behavior expected from robust Windows service wrappers.

The Shutdown Sequence

When a system shutdown or reboot is detected, Servy executes a specialized teardown workflow designed to ensure data integrity and a graceful exit. The sequence is as follows:

1. Pre-Shutdown Event: Servy immediately captures the SERVICE_CONTROL_PRESHUTDOWN signal from the Windows Service Control Manager (SCM).
2. Pre-Stop Hook: If a Pre-Stop hook is configured, it is executed. By default, this runs synchronously to allow for cleanup. However, if the Pre-Stop Timeout is set to 0, the hook runs in fire-and-forget mode and Servy proceeds immediately to the next step.
3. Process Termination: Servy stops the managed child process. It first attempts a graceful close (sending WM_CLOSE or CTRL_C_EVENT) before resorting to a forced termination if the process does not exit within the configured timeout.
4. Post-Stop Hook: If a Post-Stop hook is configured, it is executed in fire-and-forget mode. This hook runs after the child process has exited but does not block the service from finishing its own shutdown.
5. Logging & Finalization: Servy logs the successful completion of the pre-shutdown sequence to the Windows Event Log and officially transitions to the STOPPED state.

Key Features

• Pre-Shutdown Registration: Registers for SERVICE_CONTROL_PRESHUTDOWN. This allows Servy to begin cleanup immediately when an OS shutdown or reboot is initiated, occurring before the standard service stop command is issued.
• SCM Progress Reporting: Periodically reports progress using wait hints and checkpoints to the Windows Service Control Manager (SCM), preventing premature termination during long cleanup tasks.
• Synchronized Teardown: Protects against race conditions when STOP and PRESHUTDOWN control codes are received concurrently.

Mandatory Reinstallation

Important

Compatibility: You must reinstall your service using Servy v6.2+. Services installed with earlier versions lack the SERVICE_ACCEPT_PRESHUTDOWN flag in the SCM database and will ignore these high-priority notifications.

Extending the Shutdown Window

By default, Windows provides a limited grace period for services to stop during system shutdown. If your service and all configured shutdown hooks complete within approximately 20 to 30 seconds, additional configuration is likely unnecessary.

However, if your service requires more time (for example, to drain long running connections or flush large buffers), you must increase the global operating system timeouts. The Service Control Manager reads these values only during system startup, so a full reboot is required after applying changes.

The following PowerShell script extends the shutdown timeouts. Run it as Administrator, set the desired timeout in milliseconds, and then reboot the system.

# Registry path
$registryPath = "HKLM:\SYSTEM\CurrentControlSet\Control"

# Timeout in milliseconds (example: 80 seconds)
$timeoutValue = 80000

# 1. Set PreshutdownTimeout (DWORD, milliseconds)
if (Get-ItemProperty -Path $registryPath -Name "PreshutdownTimeout" -ErrorAction SilentlyContinue) {
    Set-ItemProperty -Path $registryPath -Name "PreshutdownTimeout" -Value $timeoutValue
} else {
    New-ItemProperty -Path $registryPath -Name "PreshutdownTimeout" -Value $timeoutValue -PropertyType DWord -Force
}

# 2. Set WaitToKillServiceTimeout (REG_SZ, milliseconds)
# Note: This is stored as a string (REG_SZ) in the Windows Registry
Set-ItemProperty -Path $registryPath -Name "WaitToKillServiceTimeout" -Value "$timeoutValue"

Write-Host "Shutdown timeouts updated to $timeoutValue ms."
Write-Host "A system reboot is required for these changes to take effect."

Notes

• PreshutdownTimeout: This defines how long Windows waits for services that specifically handle pre-shutdown notifications before moving to the next shutdown phase.
• WaitToKillServiceTimeout: This defines the global time Windows waits for all services to stop before forcing termination of the remaining processes.
• Configuration Tip: Set $timeoutValue to the maximum time required for your longest running service and its associated shutdown hooks to complete cleanly.