Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions ParallelKit.Harness.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ $ErrorActionPreference = "Stop"
# The whole suite runs under strict mode: a host project may well use it,
# and the kit must not depend on lenient hashtable/variable reads.
Set-StrictMode -Version Latest
# The thread pool's minimum before the kit loads: the kit leaves it alone.
$poolMinBefore = 0; $poolIoBefore = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]$poolMinBefore, [ref]$poolIoBefore)
. (Join-Path $PSScriptRoot "ParallelKit.ps1")

$script:passCount = 0
Expand Down Expand Up @@ -75,10 +78,10 @@ Write-Host "=== A: setup ===" -ForegroundColor Cyan
$init = Initialize-ParallelKit -MaxConcurrentProcesses 8
Test-Assert ($init.AbortHandler -eq $true) "abort handler registers"
Test-Assert ($init.ChildProcessJob -eq $true) "child-process job object initializes"
Test-Assert ($init.ThreadPool -eq $true) "thread pool minimum is raised"
Test-Assert ($init.ThreadPool -eq $true) "ThreadPool is still `$true, for scripts that check it"
$w = 0; $io = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]$w, [ref]$io)
Test-Assert ($w -ge 128) "thread pool minimum is at least 128 worker threads"
Test-Assert ($w -eq $poolMinBefore -and $io -eq $poolIoBefore) ("Initialize-ParallelKit leaves the thread pool's minimum alone (" + $w + "/" + $io + ", was " + $poolMinBefore + "/" + $poolIoBefore + ")")
Write-Host ""

# ==============================================================================
Expand Down Expand Up @@ -854,24 +857,27 @@ $writer.Dispose()
Test-Assert ($null -eq $scanError) ("scanning a collection other threads are changing doesn't throw (" + $scanError + ")")

# With no Initialize-ParallelKit at all, starting a process sets up the
# thread pool and the kill-on-close job object. Needs a fresh process.
# kill-on-close job object, and leaves the thread pool alone. Needs a fresh
# process.
$probeScript = Join-Path $env:TEMP ("pk-probe-" + [guid]::NewGuid().ToString("N") + ".ps1")
$kitPath = Join-Path $PSScriptRoot "ParallelKit.ps1"
[System.IO.File]::WriteAllText($probeScript, @"
`$w0 = 0; `$io0 = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]`$w0, [ref]`$io0)
. '$kitPath'
`$before = [PkChildProcessJob]::IsInitialized
`$j = Start-PkProcess -FilePath '$cmdExe' -Arguments '/c exit 0'
`$null = Wait-PkProcess -Process `$j.Proc -TimeoutMs 5000
`$w = 0; `$io = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]`$w, [ref]`$io)
Write-Output ("before=" + `$before + " after=" + [PkChildProcessJob]::IsInitialized + " threads=" + `$w)
Write-Output ("before=" + `$before + " after=" + [PkChildProcessJob]::IsInitialized + " threads=" + `$w + " was=" + `$w0)
"@)
$probe = Invoke-PkProcessWithTimeout -FilePath $selfExe -Arguments ('-NoProfile -ExecutionPolicy Bypass -File "' + $probeScript + '"') -TimeoutMs 60000
[System.IO.File]::Delete($probeScript)
Test-Assert ($probe.Stdout -match 'before=False after=True') ("starting a process sets up child cleanup by itself (" + ([string]$probe.Stdout).Trim() + ")")
$probeThreads = 0
if ($probe.Stdout -match 'threads=(\d+)') { $probeThreads = [int]$Matches[1] }
Test-Assert ($probeThreads -ge 128) ("and raises the thread pool by itself (minimum " + $probeThreads + ")")
$probeThreads = -1; $probeWas = -2
if ($probe.Stdout -match 'threads=(\d+) was=(\d+)') { $probeThreads = [int]$Matches[1]; $probeWas = [int]$Matches[2] }
Test-Assert ($probeThreads -eq $probeWas) ("and leaves the thread pool's minimum alone (" + $probeThreads + ", was " + $probeWas + ")")

# A script run the way a prompt runs it (& script, or .\script.ps1) holds
# the kit's functions in its own scope, where a .GetNewClosure() block can't
Expand Down Expand Up @@ -914,12 +920,12 @@ $clm = Invoke-PkProcessWithTimeout -FilePath $selfExe -Arguments ('-NoProfile -E
[System.IO.File]::Delete($clmScript)
Test-Assert ($clm.Stdout -like '*ConstrainedLanguage mode, but the kit needs FullLanguage*') ("loading in Constrained Language Mode fails with a message naming the problem (" + ([string]$clm.Stdout).Trim() + ")")

# The dispatcher sizes the pool for its own concurrency.
# The dispatcher leaves the pool alone, whatever its concurrency.
$feed = @{ Given = $false }
$null = Invoke-PkProcessDispatch -MaxConcurrent 100 -GroupProvider { return $null } -JobBuilder { param($g) } -JobFinalize { param($j, $p) }
$w = 0; $io = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]$w, [ref]$io)
Test-Assert ($w -ge 232) ("the dispatcher raises the thread pool to fit -MaxConcurrent (minimum " + $w + " for 100 processes)")
Test-Assert ($w -eq $poolMinBefore) ("the dispatcher leaves the thread pool's minimum alone at -MaxConcurrent 100 (" + $w + ", was " + $poolMinBefore + ")")

# A one-line starter keeps the caller's job fields.
Reset-Harness
Expand Down Expand Up @@ -1102,12 +1108,12 @@ $threw = $false
try { $null = Invoke-PkRunspaceJobs -MaxParallel 1 -JobParams @(@{ Id = 1 }, $null) -WorkerScript { param($Id) } } catch { $threw = ($_.ToString() -like '*entry 1 is not a hashtable*') }
Test-Assert $threw "-JobParams with a `$null entry fails the same way"

# A shared budget sizes the thread pool too.
# So does a shared budget.
$bigBudget = [System.Threading.SemaphoreSlim]::new(150, 150)
$null = Invoke-PkProcessDispatch -MaxConcurrent $bigBudget -GroupProvider { return $null } -JobBuilder { param($g) } -JobFinalize { param($j, $p) }
$w = 0; $io = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]$w, [ref]$io)
Test-Assert ($w -ge 332) ("a shared budget of 150 raises the thread pool to fit (minimum " + $w + ")")
Test-Assert ($w -eq $poolMinBefore) ("and with a shared budget of 150 (" + $w + ", was " + $poolMinBefore + ")")
$bigBudget.Dispose()
Write-Host ""

Expand Down
40 changes: 11 additions & 29 deletions ParallelKit.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -1055,32 +1055,19 @@ function Initialize-PkChildProcessJob {
return $false
}

function Initialize-PkThreadPool {
# Raises the pool's minimum, since the pool grows slowly past it. This was
# for the output reads, two per program; those now run on threads of their
# own (PkStreamReadTask), so the kit's own work doesn't depend on it.
param([int]$MaxConcurrentProcesses = 0)
$clampedProcs = [Math]::Min([Math]::Max($MaxConcurrentProcesses, 0), 16000)
$minimumWorkerThreads = [Math]::Max(128, (2 * $clampedProcs) + 32)
$worker = 0; $io = 0
[System.Threading.ThreadPool]::GetMinThreads([ref]$worker, [ref]$io)
[PkState]::ThreadPoolRaised = $true
if ($worker -ge $minimumWorkerThreads) { return $true }
return [System.Threading.ThreadPool]::SetMinThreads($minimumWorkerThreads, $io)
}

function Initialize-ParallelKit {
# .SYNOPSIS
# Sets up Ctrl+C handling, child-process cleanup and the thread pool up front. Optional.
# Sets up Ctrl+C handling and child-process cleanup up front. Optional.
# .DESCRIPTION
# The engines set up what they need on first use anyway. Safe to call more than
# once. A failed Ctrl+C handler or child-process cleanup also prints a warning.
# .PARAMETER MaxConcurrentProcesses
# How many programs you expect to run at once, used to size the thread pool.
# 0 (the default) sizes it for up to about 48.
# Not used since 3.4, which leaves the thread pool's settings alone; kept so
# existing calls still work.
# .OUTPUTS
# An object with AbortHandler, ChildProcessJob and ThreadPool, each $true if that
# part worked; Version, the kit's version; and StartMode, how the kit starts
# An object with AbortHandler and ChildProcessJob, each $true if that part
# worked; ThreadPool, always $true since 3.4 (kept for scripts that check
# it); Version, the kit's version; and StartMode, how the kit starts
# programs here: CreatedInJob (inside the Job Object, so anything they start
# is in it too), AddedToJob (started, then added to it just after), or NoJob
# (no cleanup if PowerShell is killed). A program whose start can't be set up
Expand All @@ -1089,7 +1076,10 @@ function Initialize-ParallelKit {
param([int]$MaxConcurrentProcesses = 0)
$handlerOk = Register-PkAbortHandler
$jobOk = Initialize-PkChildProcessJob
$poolOk = Initialize-PkThreadPool -MaxConcurrentProcesses $MaxConcurrentProcesses
# The kit used to raise the thread pool's minimum here, for output reads on
# pool threads. Those have threads of their own now (PkStreamReadTask), and
# the minimum is a setting the caller's own code shares.
$poolOk = $true
# The header's Version line: the version PR changes both, and the harness
# checks they match.
$version = [version]'3.3'
Expand Down Expand Up @@ -1553,7 +1543,6 @@ function Start-PkProcessCore {
$commandLine = Resolve-PkArguments -Arguments $Arguments -FilePath $FilePath
# For a caller who never ran Initialize-ParallelKit. No-ops once done.
if (-not [PkChildProcessJob]::IsInitialized) { $null = [PkChildProcessJob]::Initialize() }
if (-not [PkState]::ThreadPoolRaised) { $null = Initialize-PkThreadPool }

$psi = [System.Diagnostics.ProcessStartInfo]::new()
$psi.FileName = $FilePath
Expand Down Expand Up @@ -2241,13 +2230,6 @@ function Invoke-PkProcessDispatch {
throw ("Invoke-PkProcessDispatch: -MaxOutputChars must be 0 (no cap) or more (got " + $pkMaxOutputChars + "). It's how many characters of each job's output streams to keep.")
}

# Size the thread pool up front. For a shared budget, its free slots now
# are the best measure of its size.
$pkPoolSizeHint = 0
if ($pkMaxConcurrent -is [int]) { $pkPoolSizeHint = $pkMaxConcurrent }
elseif ($pkMaxConcurrent -is [System.Threading.SemaphoreSlim]) { $pkPoolSizeHint = $pkMaxConcurrent.CurrentCount }
$null = Initialize-PkThreadPool -MaxConcurrentProcesses $pkPoolSizeHint

if ($null -eq $pkJobStarter) {
$pkCallerState = $PSCmdlet.SessionState
$pkJobStarter = {
Expand Down Expand Up @@ -3064,7 +3046,7 @@ function Invoke-PkProcessBatch {

function Get-PkWorkerSafeFunctionNames {
# Kit functions every worker runspace gets automatically.
return @('Write-PkMessage', 'Test-PkAbortSignal', 'Test-PkCancelRequested', 'Initialize-PkThreadPool', 'Stop-PkProcessTree', 'Stop-PkProcessTreeCore', 'Split-PkTaskkillArguments', 'Stop-PkJobProcesses', 'Get-PkProcessDuration', 'Resolve-PkEncoding',
return @('Write-PkMessage', 'Test-PkAbortSignal', 'Test-PkCancelRequested', 'Stop-PkProcessTree', 'Stop-PkProcessTreeCore', 'Split-PkTaskkillArguments', 'Stop-PkJobProcesses', 'Get-PkProcessDuration', 'Resolve-PkEncoding',
'Start-PkProcess', 'Wait-PkProcess', 'Wait-PkRunningJobs', 'Complete-PkProcess', 'Invoke-PkProcessWithTimeout',
'Invoke-PkProcessDispatch', 'Invoke-PkProcessDispatchCore', 'Invoke-PkProcessBatch',
'Register-PkCancellationSource', 'Unregister-PkCancellationSource', 'New-PkBatchResult', 'Get-PkJobMaxOutputChars', 'ConvertTo-PkArgumentString', 'Get-PkForceStopReason', 'Resolve-PkFileSystemPath', 'Add-PkDispatchGroupJobs', 'Start-PkProcessCore', 'Get-PkJobTimeLimit', 'Stop-PkTimedOutJob', 'Get-PkStartFailureCause', 'Resolve-PkArguments', 'Invoke-PkCallback', 'Write-PkCallbackLoopWarning', 'ConvertTo-PkArgumentStringCore')
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Requires Windows, with Windows PowerShell 5.1 or PowerShell 7. Download `Paralle

```powershell
. "$PSScriptRoot\ParallelKit.ps1"
$null = Initialize-ParallelKit -MaxConcurrentProcesses 8
$null = Initialize-ParallelKit
```

If you downloaded the file, Windows marks it as coming from the internet and your execution policy may refuse to load it. Run `Unblock-File .\ParallelKit.ps1` once to clear that.
Expand All @@ -99,7 +99,7 @@ Dot-source it. It loads itself as an in-memory module named `ParallelKit`: nothi

Its public functions are imported globally, so they stay available for the rest of that PowerShell session, and a `.GetNewClosure()` block can call them however your script was started. Its internal helpers stay inside the module.

`Initialize-ParallelKit` is optional. It registers the Ctrl+C handler, sets up child-process cleanup and sizes the thread pool up front; the engines set up what they need on first use either way. It returns an object with `AbortHandler`, `ChildProcessJob` and `ThreadPool`, each `$true` if that part worked (a failed abort handler or child-process cleanup also prints a warning), `Version`, the kit's version, and `StartMode`, how the kit starts programs here: `CreatedInJob` (inside the Job Object, the normal case), `AddedToJob` (started, then added to it just after) or `NoJob` (no cleanup if PowerShell is killed). It's the default for the session, not a promise for every program: one whose start can't be set up inside the Job Object falls back to `AddedToJob`, with a warning.
`Initialize-ParallelKit` is optional. It registers the Ctrl+C handler and sets up child-process cleanup up front; the engines set up what they need on first use either way. The kit leaves the thread pool's settings alone. It returns an object with `AbortHandler` and `ChildProcessJob`, each `$true` if that part worked (a failure also prints a warning), `ThreadPool`, always `$true` (kept for scripts that check it), `Version`, the kit's version, and `StartMode`, how the kit starts programs here: `CreatedInJob` (inside the Job Object, the normal case), `AddedToJob` (started, then added to it just after) or `NoJob` (no cleanup if PowerShell is killed). It's the default for the session, not a promise for every program: one whose start can't be set up inside the Job Object falls back to `AddedToJob`, with a warning.

Each public function has built-in help: `Get-Help Invoke-PkProcessBatch -Full` shows its parameters, their defaults, what it returns and an example.

Expand Down
Loading