From 3e496a8368387b3be838d485171e951b0aa0e178 Mon Sep 17 00:00:00 2001 From: Hal <22532613+HalRiveria@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:23:48 -0500 Subject: [PATCH 1/2] Add -StreamTimeoutMs to Invoke-PkProcessBatch and Invoke-PkProcessDispatch Co-Authored-By: Claude Opus 5.5 --- ParallelKit.Harness.ps1 | 68 ++++++++++++++++++++++++++++++++++++ ParallelKit.ps1 | 76 ++++++++++++++++++++++++++++------------- README.md | 6 ++-- 3 files changed, 123 insertions(+), 27 deletions(-) diff --git a/ParallelKit.Harness.ps1 b/ParallelKit.Harness.ps1 index 61ea44e..191a226 100644 --- a/ParallelKit.Harness.ps1 +++ b/ParallelKit.Harness.ps1 @@ -4726,6 +4726,74 @@ try { $bcOk = (Invoke-PkProcessWithTimeout -FilePath $cmdExe -Arguments '/d /c e Test-Assert ($bcOk -match '^ok') ("a program runs with -OutputEncoding '65001' ('" + ([string]$bcOk).Trim() + "')") Write-Host "" +Write-Host "=== BD: -StreamTimeoutMs on the batch and the dispatcher ===" -ForegroundColor Cyan +# The wait for held output was fixed at 15 s in both, and since the wait +# moved into the dispatcher's default poll, a shorter -StreamTimeoutMs passed +# to Complete-PkProcess in -JobFinalize no longer shortened it. Each held +# command leaves a ping (-w 4321, BB's helpers) holding its output for 8 s. +Reset-Harness +function Invoke-HarnessHeldDispatch { + param([int]$StreamTimeoutMs, $FinalizeTimeoutMs) + $feed = @{ Given = $false } + $got = @{} + $jobs = @(New-HarnessHeldCommand -Seconds 8 -Key 'held') + $sw = [System.Diagnostics.Stopwatch]::StartNew() + $null = Invoke-PkProcessDispatch -MaxConcurrent 1 -StreamTimeoutMs $StreamTimeoutMs ` + -GroupProvider { if ($feed.Given) { return $null }; $feed.Given = $true; return @{ Name = 'held' } }.GetNewClosure() ` + -JobBuilder { param($g) return $jobs }.GetNewClosure() ` + -JobFinalize { + param($j, $q) + if ($null -eq $FinalizeTimeoutMs) { $got.R = Complete-PkProcess -Job $j } else { $got.R = Complete-PkProcess -Job $j -StreamTimeoutMs $FinalizeTimeoutMs } + }.GetNewClosure() + $sw.Stop() + return @{ Result = $got.R; Seconds = [math]::Round($sw.Elapsed.TotalSeconds, 1) } +} +try { + $bdOut = $null; $bdError = $null + $sw = [System.Diagnostics.Stopwatch]::StartNew() + try { $bdOut = Invoke-PkProcessBatch -StreamTimeoutMs 1000 -Commands @(New-HarnessHeldCommand -Seconds 8 -Key 'held') } catch { $bdError = [string]$_ } + $sw.Stop() + $bdR = $null; if ($null -ne $bdOut) { $bdR = @($bdOut.Results)[0] } + Test-Assert ($null -ne $bdR -and $bdR.StreamTimedOut -and $bdR.Stdout -match 'held' -and $sw.Elapsed.TotalSeconds -lt 4) ("batch -StreamTimeoutMs 1000: held output is given up on after about a second, with what arrived (" + [math]::Round($sw.Elapsed.TotalSeconds, 1) + " s" + $(if ($bdError) { ", error: " + $bdError }) + ")") + Stop-HarnessTaggedPings + + $bdOut = $null; $bdError = $null + $sw = [System.Diagnostics.Stopwatch]::StartNew() + try { $bdOut = Invoke-PkProcessBatch -StreamTimeoutMs 0 -Commands @(New-HarnessHeldCommand -Seconds 8 -Key 'held') } catch { $bdError = [string]$_ } + $sw.Stop() + $bdR = $null; if ($null -ne $bdOut) { $bdR = @($bdOut.Results)[0] } + Test-Assert ($null -ne $bdR -and $bdR.StreamTimedOut -and $sw.Elapsed.TotalSeconds -lt 3) ("batch -StreamTimeoutMs 0: doesn't wait for held output (" + [math]::Round($sw.Elapsed.TotalSeconds, 1) + " s" + $(if ($bdError) { ", error: " + $bdError }) + ")") + Stop-HarnessTaggedPings + + # The dispatcher: Complete-PkProcess with no -StreamTimeoutMs of its own + # uses the dispatcher's, so it doesn't wait again; one with its own waits + # only the rest. + $bdRun = $null; $bdError = $null + try { $bdRun = Invoke-HarnessHeldDispatch -StreamTimeoutMs 1000 -FinalizeTimeoutMs $null } catch { $bdError = [string]$_ } + Test-Assert ($null -ne $bdRun -and $bdRun.Result.StreamTimedOut -and $bdRun.Result.Stdout -match 'held' -and $bdRun.Seconds -lt 4) ("dispatcher -StreamTimeoutMs 1000: a plain Complete-PkProcess in -JobFinalize doesn't wait a second time (" + $(if ($bdRun) { [string]$bdRun.Seconds + " s" } else { $bdError }) + ")") + Stop-HarnessTaggedPings + $bdRun = $null; $bdError = $null + try { $bdRun = Invoke-HarnessHeldDispatch -StreamTimeoutMs 1000 -FinalizeTimeoutMs 3000 } catch { $bdError = [string]$_ } + Test-Assert ($null -ne $bdRun -and $bdRun.Result.StreamTimedOut -and $bdRun.Seconds -ge 2.5 -and $bdRun.Seconds -lt 6) ("dispatcher -StreamTimeoutMs 1000, Complete-PkProcess -StreamTimeoutMs 3000: waits the rest, about 3 s in all (" + $(if ($bdRun) { [string]$bdRun.Seconds + " s" } else { $bdError }) + ")") + Stop-HarnessTaggedPings + + # A negative value is refused before anything starts. + $bdStarted = @{ Count = 0 } + $bdErrors = @() + foreach ($bdWhich in 'batch', 'dispatcher') { + $bdError = $null + try { + if ($bdWhich -eq 'batch') { $null = Invoke-PkProcessBatch -StreamTimeoutMs -1 -Commands @(@{ FilePath = $cmdExe; Arguments = '/c exit 0' }) } + else { $null = Invoke-PkProcessDispatch -MaxConcurrent 1 -StreamTimeoutMs -1 -GroupProvider { $bdStarted.Count++; return $null }.GetNewClosure() -JobBuilder { param($g) } -JobFinalize { param($j, $q) } } + } catch { $bdError = [string]$_ } + $bdErrors += $bdError + } + Test-Assert ($bdErrors[0] -like 'Invoke-PkProcessBatch: -StreamTimeoutMs must be 0 or more (got -1)*' -and $bdErrors[1] -like 'Invoke-PkProcessDispatch: -StreamTimeoutMs must be 0 or more (got -1)*' -and $bdStarted.Count -eq 0) ("-StreamTimeoutMs -1 is refused by both before anything starts (" + ($bdErrors -join ' | ') + ")") +} finally { + Stop-HarnessTaggedPings +} +Write-Host "" + Set-PkMessageHandler -Handler $null Reset-PkAbortState diff --git a/ParallelKit.ps1 b/ParallelKit.ps1 index 003ee1d..f223f04 100644 --- a/ParallelKit.ps1 +++ b/ParallelKit.ps1 @@ -1798,7 +1798,8 @@ function Complete-PkProcess { # How long to wait for the output after the program exits, # in milliseconds (default 15000); 0 or more, and 0 doesn't wait. On a job # the dispatcher's default -JobPollCompleted has already waited on, only - # what's left of it, so with the default nothing. + # what's left of it after that wait. Not given there, it's the + # dispatcher's own -StreamTimeoutMs, so nothing is left. # .PARAMETER Dispose # Dispose the process object afterwards. # .OUTPUTS @@ -1811,7 +1812,8 @@ function Complete-PkProcess { param( [Parameter(Mandatory, Position = 0)] [hashtable]$Job, - # The dispatcher's default -JobPollCompleted waits the same 15 s: keep the two in step. + # Invoke-PkProcessDispatch's and Invoke-PkProcessBatch's -StreamTimeoutMs + # default to the same 15000: keep the three in step. [int]$StreamTimeoutMs = 15000, [switch]$Dispose ) @@ -1833,8 +1835,12 @@ function Complete-PkProcess { # final pass after an abort's wait sets OutputWaitOver: at most 250 ms # then, enough for a program that exited just before to have its output # read to the end, short enough for a window close. - $waitMs = $StreamTimeoutMs - if ($Job['OutputWait'] -is [System.Diagnostics.Stopwatch]) { $waitMs = [int][Math]::Max(0, $StreamTimeoutMs - $Job['OutputWait'].ElapsedMilliseconds) } + # OutputWaitMs is the dispatcher's -StreamTimeoutMs, used when the caller + # passes none of its own. + $limitMs = $StreamTimeoutMs + if (-not $PSBoundParameters.ContainsKey('StreamTimeoutMs') -and $Job['OutputWaitMs'] -is [int]) { $limitMs = $Job['OutputWaitMs'] } + $waitMs = $limitMs + if ($Job['OutputWait'] -is [System.Diagnostics.Stopwatch]) { $waitMs = [int][Math]::Max(0, $limitMs - $Job['OutputWait'].ElapsedMilliseconds) } if ($Job['OutputWaitOver']) { $waitMs = [Math]::Min($waitMs, 250) } if ($tasks.Count -gt 0) { try { @@ -1961,7 +1967,7 @@ function Invoke-PkProcessDispatch { # The dispatcher keeps its own state on each job hashtable. Don't use these keys # for anything else: GroupKey, SlotReleased, Proc, StdoutTask, StderrTask, # Stopwatch, TimeLimit, TimedOut, StartFailureReported, OutputWait, - # OutputWaitOver. It also sets Group to + # OutputWaitOver, OutputWaitMs. It also sets Group to # the job's group, unless the job already has a Group of its own. The default # starter reads FilePath, Arguments (a string as written, or a list quoted one # argument per element), WorkingDirectory and OutputEncoding from the job. A @@ -1979,8 +1985,8 @@ function Invoke-PkProcessDispatch { # .PARAMETER JobPollCompleted # { param($job) } returning $true once the job is finished. Only its last # output value counts. Default: once the program has exited and its output - # has been read, or 15 s after the exit if a program it started holds the - # output open (the job keeps its slot meanwhile), so Complete-PkProcess in + # has been read, or -StreamTimeoutMs after the exit if a program it started + # holds the output open (the job keeps its slot meanwhile), so Complete-PkProcess in # -JobFinalize doesn't wait and the other jobs carry on. # .PARAMETER JobFinalize # { param($job, $pendingQueue) } called once per finished job; collect its @@ -2016,6 +2022,10 @@ function Invoke-PkProcessDispatch { # (default 0, no limit). A job's own TimeoutSeconds key overrides it, and 0 there # opts the job out. The killed job still goes through -JobFinalize, with # $job['TimedOut'] = $true. A job whose .Proc isn't a process isn't timed. + # .PARAMETER StreamTimeoutMs + # How long the default -JobPollCompleted waits for a job's output after its + # program exits, in milliseconds (default 15000); 0 or more, and 0 doesn't + # wait. Complete-PkProcess in -JobFinalize uses it too, unless given its own. # .OUTPUTS # An object with GroupResults, Aborted, ForceKilledCount and # JobStarterFailedCount. Each group result has GroupInfo (the group), Completed @@ -2041,7 +2051,8 @@ function Invoke-PkProcessDispatch { [int]$AbortTimeoutSeconds = 60, [int]$MaxQueueAhead = 3, [scriptblock]$GroupReleaseCheck = $null, - [double]$TimeoutSeconds = 0 + [double]$TimeoutSeconds = 0, + [int]$StreamTimeoutMs = 15000 ) # pk-prefixed, parameters included: inside a worker runspace the kit isn't # a module, so a callback without .GetNewClosure() sees this frame's @@ -2060,7 +2071,8 @@ function Invoke-PkProcessDispatch { $pkMaxQueueAhead = $MaxQueueAhead $pkGroupReleaseCheck = $GroupReleaseCheck $pkTimeoutSeconds = $TimeoutSeconds - Remove-Variable -Name GroupProvider, JobBuilder, JobStarter, JobPollCompleted, JobFinalize, JobAbortCleanup, GroupCompleteCallback, MaxConcurrent, PollCallback, CancelToken, AbortTimeoutSeconds, MaxQueueAhead, GroupReleaseCheck, TimeoutSeconds -Scope Local + $pkStreamTimeoutMs = $StreamTimeoutMs + Remove-Variable -Name GroupProvider, JobBuilder, JobStarter, JobPollCompleted, JobFinalize, JobAbortCleanup, GroupCompleteCallback, MaxConcurrent, PollCallback, CancelToken, AbortTimeoutSeconds, MaxQueueAhead, GroupReleaseCheck, TimeoutSeconds, StreamTimeoutMs -Scope Local # 0 or less would never start a job (or pull a group) and spin forever. if ($pkMaxConcurrent -isnot [System.Threading.SemaphoreSlim]) { @@ -2071,9 +2083,9 @@ function Invoke-PkProcessDispatch { $pkMaxConcurrent = $pkMaxConcurrentInt } if ($pkMaxQueueAhead -lt 1) { throw "Invoke-PkProcessDispatch: -MaxQueueAhead must be at least 1." } - # Invoke-PkProcessBatch makes the same -MaxConcurrent, -TimeoutSeconds and - # -AbortTimeoutSeconds checks, so its errors name the batch: keep the two in - # step. NaN and +Infinity pass a `-lt 0` test and acted as no limit. A job's + # Invoke-PkProcessBatch makes the same -MaxConcurrent, -TimeoutSeconds, + # -AbortTimeoutSeconds and -StreamTimeoutMs checks, so its errors name the + # batch: keep the two in step. NaN and +Infinity pass a `-lt 0` test and acted as no limit. A job's # own TimeoutSeconds key follows the same rule (Get-PkJobTimeLimit). if ([double]::IsNaN($pkTimeoutSeconds) -or [double]::IsInfinity($pkTimeoutSeconds) -or $pkTimeoutSeconds -lt 0) { throw ("Invoke-PkProcessDispatch: -TimeoutSeconds must be a number of seconds, 0 (no limit) or more (got " + $pkTimeoutSeconds + ").") @@ -2081,6 +2093,9 @@ function Invoke-PkProcessDispatch { if ($pkAbortTimeoutSeconds -lt 0) { throw ("Invoke-PkProcessDispatch: -AbortTimeoutSeconds must be 0 or more (got " + $pkAbortTimeoutSeconds + "). It's how long an abort waits for running jobs before force-stopping them; 0 doesn't wait.") } + if ($pkStreamTimeoutMs -lt 0) { + throw ("Invoke-PkProcessDispatch: -StreamTimeoutMs must be 0 or more (got " + $pkStreamTimeoutMs + "). It's how long to wait for a job's output after its program exits, in milliseconds; 0 doesn't wait.") + } # Size the thread pool up front. For a shared budget, its free slots now # are the best measure of its size. @@ -2107,20 +2122,23 @@ function Invoke-PkProcessDispatch { # Done once the program has exited and its output has been read, so # Complete-PkProcess in -JobFinalize has nothing to wait for: waiting # there would stall the whole loop. A job whose output a leftover - # program holds open keeps its slot until the reads end or 15 s pass - # (Complete-PkProcess's default -StreamTimeoutMs; keep the two in - # step), timed by OutputWait, which Complete-PkProcess reads. After an - # abort's wait the final pass sets OutputWaitOver: it takes what has - # arrived. + # program holds open keeps its slot until the reads end or + # -StreamTimeoutMs passes, timed by OutputWait. The limit goes on the + # job as OutputWaitMs, so a Complete-PkProcess given no -StreamTimeoutMs + # of its own waits only what's left of it (nothing). After an abort's + # wait the final pass sets OutputWaitOver: it takes what has arrived. + # A closure, for $pkStreamTimeoutMs: a callback here only sees this + # frame's variables through dynamic scope, which a user's own + # variables could shadow. $pkJobPollCompleted = { param($pkJob) if (-not $pkJob['Proc'].HasExited) { return $false } $pkOut = $pkJob['StdoutTask']; $pkErr = $pkJob['StderrTask'] if (($pkOut -isnot [System.Threading.Tasks.Task] -or $pkOut.IsCompleted) -and ($pkErr -isnot [System.Threading.Tasks.Task] -or $pkErr.IsCompleted)) { return $true } if ($pkJob['OutputWaitOver']) { return $true } - if ($pkJob['OutputWait'] -isnot [System.Diagnostics.Stopwatch]) { $pkJob['OutputWait'] = [System.Diagnostics.Stopwatch]::StartNew() } - return ($pkJob['OutputWait'].ElapsedMilliseconds -ge 15000) - } + if ($pkJob['OutputWait'] -isnot [System.Diagnostics.Stopwatch]) { $pkJob['OutputWaitMs'] = $pkStreamTimeoutMs; $pkJob['OutputWait'] = [System.Diagnostics.Stopwatch]::StartNew() } + return ($pkJob['OutputWait'].ElapsedMilliseconds -ge $pkJob['OutputWaitMs']) + }.GetNewClosure() } if ($null -eq $pkJobAbortCleanup) { $pkJobAbortCleanup = { param($pkJob) } } if ($null -eq $pkGroupCompleteCallback) { $pkGroupCompleteCallback = { param($pkGroup) } } @@ -2339,7 +2357,7 @@ function Invoke-PkProcessDispatchCore { # its old, disposed process: cleared first. if ($pkJob['SlotReleased']) { $pkJob['Proc'] = $null; $pkJob['StdoutTask'] = $null; $pkJob['StderrTask'] = $null; $pkJob['Stopwatch'] = $null - $pkJob['OutputWait'] = $null; $pkJob['OutputWaitOver'] = $null + $pkJob['OutputWait'] = $null; $pkJob['OutputWaitOver'] = $null; $pkJob['OutputWaitMs'] = $null } $pkJob['SlotReleased'] = $false $pkStarting = $pkJob @@ -2714,6 +2732,10 @@ function Invoke-PkProcessBatch { # .PARAMETER OutputEncoding # How to decode every program's output: a name like 'utf-8', a code page number # (65001 or '65001'), or a [System.Text.Encoding]. Default: the console's code page. + # .PARAMETER StreamTimeoutMs + # How long to wait for a program's output after it exits, in milliseconds + # (default 15000); 0 or more, and 0 doesn't wait. Past it, the result has + # StreamTimedOut = $true and the output that arrived. # .OUTPUTS # An object with Results, Aborted and ForceKilledCount. Each result has Command, # ExitCode, Stdout, Stderr, StreamTimedOut, StreamError, StartError, Aborted, @@ -2733,7 +2755,8 @@ function Invoke-PkProcessBatch { [Alias('DrainTimeoutSeconds')] [int]$AbortTimeoutSeconds = 60, [double]$TimeoutSeconds = 0, - $OutputEncoding = $null + $OutputEncoding = $null, + [int]$StreamTimeoutMs = 15000 ) # pk-prefixed, parameters included: inside a worker runspace the kit isn't # a module, so a callback without .GetNewClosure() sees this frame's @@ -2744,11 +2767,12 @@ function Invoke-PkProcessBatch { $pkAbortTimeoutSeconds = $AbortTimeoutSeconds $pkTimeoutSeconds = $TimeoutSeconds $pkOutputEncoding = $OutputEncoding - Remove-Variable -Name Commands, MaxConcurrent, OnComplete, AbortTimeoutSeconds, TimeoutSeconds, OutputEncoding -Scope Local + $pkStreamTimeoutMs = $StreamTimeoutMs + Remove-Variable -Name Commands, MaxConcurrent, OnComplete, AbortTimeoutSeconds, TimeoutSeconds, OutputEncoding, StreamTimeoutMs -Scope Local # Checked once here, so a bad name fails the call instead of every command. $null = Resolve-PkEncoding -Encoding $pkOutputEncoding - # Invoke-PkProcessDispatch makes the same three checks; these name the + # Invoke-PkProcessDispatch makes the same four checks; these name the # batch. Keep the two in step. Get-PkJobTimeLimit checks a job's own # TimeoutSeconds key by the same rule. if ($pkMaxConcurrent -lt 1) { throw ("Invoke-PkProcessBatch: -MaxConcurrent must be at least 1 (got " + $pkMaxConcurrent + ").") } @@ -2758,6 +2782,9 @@ function Invoke-PkProcessBatch { if ($pkAbortTimeoutSeconds -lt 0) { throw ("Invoke-PkProcessBatch: -AbortTimeoutSeconds must be 0 or more (got " + $pkAbortTimeoutSeconds + "). It's how long an abort waits for running programs before force-stopping them; 0 doesn't wait.") } + if ($pkStreamTimeoutMs -lt 0) { + throw ("Invoke-PkProcessBatch: -StreamTimeoutMs must be 0 or more (got " + $pkStreamTimeoutMs + "). It's how long to wait for a program's output after it exits, in milliseconds; 0 doesn't wait.") + } $pkResults = [System.Collections.Generic.List[object]]::new() $pkState = @{ Given = $false } @@ -2856,6 +2883,7 @@ function Invoke-PkProcessBatch { GroupProvider = $pkGroupProvider; JobBuilder = $pkJobBuilder; JobStarter = $pkJobStarter JobFinalize = $pkJobFinalize; JobAbortCleanup = $pkJobAbortCleanup; MaxConcurrent = $pkMaxConcurrent AbortTimeoutSeconds = $pkAbortTimeoutSeconds; MaxQueueAhead = 1; TimeoutSeconds = $pkTimeoutSeconds + StreamTimeoutMs = $pkStreamTimeoutMs } try { $pkDispatch = Invoke-PkProcessDispatch @pkDispatchParams diff --git a/README.md b/README.md index bd9aab8..489e8e0 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ Programs run in your current location (`Get-Location`) unless a command says oth - `Aborted` is `$true` for a command an abort killed or kept from starting. - `TimedOut` is `$true` for a program `-TimeoutSeconds` killed. - `Duration` is how long the program ran, from its start to its exit or kill, as a `[TimeSpan]`: not the time it waited for a slot, nor any wait for its output afterwards. It's `$null` for a command that never started. Sorting on it finds the slow ones: `$batch.Results | Sort-Object Duration -Descending | Select-Object -First 10`. -- `StreamTimedOut` means the output read gave up 15 seconds after the program exited, on stdout, stderr or both, which only happens when a program it started is still holding the output open. Each stream comes back with what arrived before then: one held open is cut short, the other is whole. The read of a held stream carries on in the background until that program lets go of it; it's in the kit's Job Object, so that's when PowerShell exits at the latest. Until then that read keeps a thread of its own, one per held stream, so other programs' output isn't held up behind it, and drops what it reads, so a program that keeps writing doesn't fill memory with output nobody can get. What came back is that stream's text from then on, so calling `Complete-PkProcess` again on the same job returns the same text, and so does the read task's `Result` once the stream ends. `StreamError` means a read failed, and that stream comes back `$null`; it can be set alongside `StreamTimedOut` when the other stream was held open. While a program's output is held open, its command keeps its slot, but the other commands carry on: they keep starting, finishing and being killed at their time limits, and an abort is acted on at once. If an abort's wait for running programs ends while one is still waiting for its output, it gets what has arrived, with `StreamTimedOut`, rather than counting as force-stopped. +- `StreamTimedOut` means the output read gave up 15 seconds after the program exited (`-StreamTimeoutMs` changes that, in milliseconds; 0 doesn't wait), on stdout, stderr or both, which only happens when a program it started is still holding the output open. Each stream comes back with what arrived before then: one held open is cut short, the other is whole. The read of a held stream carries on in the background until that program lets go of it; it's in the kit's Job Object, so that's when PowerShell exits at the latest. Until then that read keeps a thread of its own, one per held stream, so other programs' output isn't held up behind it, and drops what it reads, so a program that keeps writing doesn't fill memory with output nobody can get. What came back is that stream's text from then on, so calling `Complete-PkProcess` again on the same job returns the same text, and so does the read task's `Result` once the stream ends. `StreamError` means a read failed, and that stream comes back `$null`; it can be set alongside `StreamTimedOut` when the other stream was held open. While a program's output is held open, its command keeps its slot, but the other commands carry on: they keep starting, finishing and being killed at their time limits, and an abort is acted on at once. If an abort's wait for running programs ends while one is still waiting for its output, it gets what has arrived, with `StreamTimedOut`, rather than counting as force-stopped. `Results` is in the order commands finished, not the order you gave them. Use `Command` to match them up, or give each command your own key (`Index = $n`) and sort on it: `$batch.Results | Sort-Object { $_.Command.Index }`. @@ -249,11 +249,11 @@ $dispatch = Invoke-PkProcessDispatch @dispatchParams All of these callbacks run on whichever thread called the dispatcher: the main thread normally, or the worker if you call it from inside a runspace job (in which case the worker rules apply to them). - **`-GroupCompleteCallback` also runs for a group an abort cut short**, so you can record the jobs in it that did finish. Before doing anything irreversible there (zipping the folder, deleting sources), check `Test-PkCancelRequested` (or your own `-CancelToken`) and skip it if true. -- `-JobFinalize` is called once per finished job. Collect its exit code and output there with `Complete-PkProcess -Job $job`; the dispatcher disposes the process right after. With the default `-JobPollCompleted`, a job is finished once its program has exited and its output has been read, or 15 seconds after the exit when a program it started holds the output open (the job keeps its slot meanwhile, and the other jobs carry on), so `Complete-PkProcess` there has nothing left to wait for. A longer `-StreamTimeoutMs` there waits only the rest, but on the dispatch loop's own thread, holding up the other jobs; a shorter one can't shorten the poll's 15 seconds. With your own `-JobPollCompleted`, `Complete-PkProcess` waits as it does anywhere else. +- `-JobFinalize` is called once per finished job. Collect its exit code and output there with `Complete-PkProcess -Job $job`; the dispatcher disposes the process right after. With the default `-JobPollCompleted`, a job is finished once its program has exited and its output has been read, or `-StreamTimeoutMs` after the exit (15 seconds by default) when a program it started holds the output open (the job keeps its slot meanwhile, and the other jobs carry on), so `Complete-PkProcess` there has nothing left to wait for: given no `-StreamTimeoutMs` of its own, it uses the dispatcher's. A longer one there waits only the rest, but on the dispatch loop's own thread, holding up the other jobs; to wait less, set the dispatcher's `-StreamTimeoutMs` instead. With your own `-JobPollCompleted`, `Complete-PkProcess` waits as it does anywhere else. - Groups are pulled lazily, at most `-MaxQueueAhead` (default 3) ahead. - A group can be any value: a hashtable, a path, a name. Each job gets its group as `$job.Group`. - Each `-GroupProvider` call outputs exactly one group, or `$null` to end, and nothing else: `return $group`, `return ,@('a', 'b', 'c')` for a list as one group (the comma keeps a one-item list a list), or `return $null`. Anything else it lets out (an `ArrayList.Add` index, say) becomes part of the group, so discard it with `$null = ...`. Output that ends in `$null` is taken as the end, with a warning, so a list group can't end in `$null`. -- The dispatcher keeps its state on the job hashtables. Don't use these names for your own job fields: `GroupKey`, `SlotReleased`, `Proc`, `StdoutTask`, `StderrTask`, `Stopwatch`, `TimeLimit`, `TimedOut`, `StartFailureReported`, `OutputWait`, `OutputWaitOver`. (`Group` is yours if you set it yourself.) +- The dispatcher keeps its state on the job hashtables. Don't use these names for your own job fields: `GroupKey`, `SlotReleased`, `Proc`, `StdoutTask`, `StderrTask`, `Stopwatch`, `TimeLimit`, `TimedOut`, `StartFailureReported`, `OutputWait`, `OutputWaitOver`, `OutputWaitMs`. (`Group` is yours if you set it yourself.) - `-TimeoutSeconds 600` kills a job's program, and anything it started, if it's still running after 10 minutes. The default, 0, means no limit, and it can be fractional. A job's own `TimeoutSeconds` key overrides it; 0 opts the job out, and a bad value is a failed start. The killed job still goes through `-JobFinalize`, where `$job['TimedOut']` is `$true`, and other jobs carry on. The limit stays in force while an abort waits for running jobs. A retry gets a fresh clock. A job whose `.Proc` isn't a process isn't timed: `-JobPollCompleted` is the place for its limit. - To retry a job or add follow-up work, enqueue job hashtables onto `$pending` inside `-JobFinalize`. They join the same group, and the group isn't complete until they've all finished. A retry can start within milliseconds of the failure, so cap the number of retries, and don't count on the gap for something like a locked file to clear. - Supply `-JobStarter { param($job) ... }` to start jobs yourself. It must set `$job.Proc` and should return the job. A starter that is just `Start-PkProcess ...` works too: its result is folded into your job. Throw to report a job that couldn't start. From 575e6b1d19aa44a803db10f4d55308312523a1e6 Mon Sep 17 00:00:00 2001 From: Hal <22532613+HalRiveria@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:41:32 -0500 Subject: [PATCH 2/2] Ignore a stray OutputWaitMs, test a re-queued job and a worker, note the shared default Co-Authored-By: Claude Opus 5.5 --- ParallelKit.Harness.ps1 | 32 ++++++++++++++++++++++++++++++++ ParallelKit.ps1 | 28 ++++++++++++++++++---------- 2 files changed, 50 insertions(+), 10 deletions(-) diff --git a/ParallelKit.Harness.ps1 b/ParallelKit.Harness.ps1 index 68f09b1..eaed3ef 100644 --- a/ParallelKit.Harness.ps1 +++ b/ParallelKit.Harness.ps1 @@ -4790,6 +4790,38 @@ try { Test-Assert ($null -ne $bdRun -and $bdRun.Result.StreamTimedOut -and $bdRun.Seconds -ge 2.5 -and $bdRun.Seconds -lt 6) ("dispatcher -StreamTimeoutMs 1000, Complete-PkProcess -StreamTimeoutMs 3000: waits the rest, about 3 s in all (" + $(if ($bdRun) { [string]$bdRun.Seconds + " s" } else { $bdError }) + ")") Stop-HarnessTaggedPings + # A job -JobFinalize re-queues waits the dispatcher's limit again, from + # its own new exit. + $bdFeed = @{ Given = $false } + $bdGot = [System.Collections.Generic.List[object]]::new() + $bdJobs = @(New-HarnessHeldCommand -Seconds 8 -Key 'again') + $bdError = $null + $sw = [System.Diagnostics.Stopwatch]::StartNew() + try { + $null = Invoke-PkProcessDispatch -MaxConcurrent 1 -StreamTimeoutMs 1000 ` + -GroupProvider { if ($bdFeed.Given) { return $null }; $bdFeed.Given = $true; return @{ Name = 'again' } }.GetNewClosure() ` + -JobBuilder { param($g) return $bdJobs }.GetNewClosure() ` + -JobFinalize { param($j, $q) $bdGot.Add((Complete-PkProcess -Job $j)); if ($bdGot.Count -eq 1) { $q.Enqueue($j) } }.GetNewClosure() + } catch { $bdError = [string]$_ } + $sw.Stop() + $bdBoth = @($bdGot | Where-Object { $_.StreamTimedOut -and $_.Stdout -match 'held' }).Count + Test-Assert ($bdGot.Count -eq 2 -and $bdBoth -eq 2 -and $sw.Elapsed.TotalSeconds -lt 5) ("dispatcher -StreamTimeoutMs 1000: a re-queued job is given up on after about a second again (" + $bdBoth + " of " + $bdGot.Count + " runs timed out with their output, " + [math]::Round($sw.Elapsed.TotalSeconds, 1) + " s" + $(if ($bdError) { ", error: " + $bdError }) + ")") + Stop-HarnessTaggedPings + + # Inside a worker the kit isn't a module: the default poll still carries + # the limit it was given. + $bdRes = [System.Collections.Generic.List[object]]::new() + $bdOut = Invoke-PkRunspaceJobs -MaxParallel 1 -JobParams @(@{ Cmd = $cmdExe }) -ResultHandler { param($r) $bdRes.Add($r) }.GetNewClosure() -WorkerScript { + param($Cmd) + $wsw = [System.Diagnostics.Stopwatch]::StartNew() + $wb = Invoke-PkProcessBatch -StreamTimeoutMs 1000 -Commands @(@{ FilePath = $Cmd; Arguments = '/d /c echo held& start /b ping -n 9 -w 4321 127.0.0.1 >nul' }) + $wr = @($wb.Results)[0] + [pscustomobject]@{ TimedOut = $wr.StreamTimedOut; Held = ($wr.Stdout -match 'held'); Seconds = [math]::Round($wsw.Elapsed.TotalSeconds, 1) } + } + $bdW = $null; if ($bdRes.Count -eq 1) { $bdW = $bdRes[0] } + Test-Assert ($bdOut.Errors.Count -eq 0 -and $null -ne $bdW -and $bdW.TimedOut -and $bdW.Held -and $bdW.Seconds -lt 4) ("a batch inside a worker honors -StreamTimeoutMs 1000 (" + $(if ($bdW) { [string]$bdW.Seconds + " s" } else { [string]$bdOut.Errors.Count + " errors: " + (@($bdOut.Errors | ForEach-Object { [string]$_.Error }) -join '; ') }) + ")") + Stop-HarnessTaggedPings + # A negative value is refused before anything starts. $bdStarted = @{ Count = 0 } $bdErrors = @() diff --git a/ParallelKit.ps1 b/ParallelKit.ps1 index f223f04..7464803 100644 --- a/ParallelKit.ps1 +++ b/ParallelKit.ps1 @@ -1835,12 +1835,15 @@ function Complete-PkProcess { # final pass after an abort's wait sets OutputWaitOver: at most 250 ms # then, enough for a program that exited just before to have its output # read to the end, short enough for a window close. - # OutputWaitMs is the dispatcher's -StreamTimeoutMs, used when the caller - # passes none of its own. + # OutputWaitMs is the dispatcher's -StreamTimeoutMs, set with OutputWait, + # and used when the caller passes none of its own. $limitMs = $StreamTimeoutMs - if (-not $PSBoundParameters.ContainsKey('StreamTimeoutMs') -and $Job['OutputWaitMs'] -is [int]) { $limitMs = $Job['OutputWaitMs'] } - $waitMs = $limitMs - if ($Job['OutputWait'] -is [System.Diagnostics.Stopwatch]) { $waitMs = [int][Math]::Max(0, $limitMs - $Job['OutputWait'].ElapsedMilliseconds) } + if ($Job['OutputWait'] -is [System.Diagnostics.Stopwatch]) { + if (-not $PSBoundParameters.ContainsKey('StreamTimeoutMs') -and $Job['OutputWaitMs'] -is [int]) { $limitMs = $Job['OutputWaitMs'] } + $waitMs = [int][Math]::Max(0, $limitMs - $Job['OutputWait'].ElapsedMilliseconds) + } else { + $waitMs = $limitMs + } if ($Job['OutputWaitOver']) { $waitMs = [Math]::Min($waitMs, 250) } if ($tasks.Count -gt 0) { try { @@ -2052,6 +2055,8 @@ function Invoke-PkProcessDispatch { [int]$MaxQueueAhead = 3, [scriptblock]$GroupReleaseCheck = $null, [double]$TimeoutSeconds = 0, + # Complete-PkProcess's and Invoke-PkProcessBatch's -StreamTimeoutMs + # default to the same 15000: keep the three in step. [int]$StreamTimeoutMs = 15000 ) # pk-prefixed, parameters included: inside a worker runspace the kit isn't @@ -2085,8 +2090,9 @@ function Invoke-PkProcessDispatch { if ($pkMaxQueueAhead -lt 1) { throw "Invoke-PkProcessDispatch: -MaxQueueAhead must be at least 1." } # Invoke-PkProcessBatch makes the same -MaxConcurrent, -TimeoutSeconds, # -AbortTimeoutSeconds and -StreamTimeoutMs checks, so its errors name the - # batch: keep the two in step. NaN and +Infinity pass a `-lt 0` test and acted as no limit. A job's - # own TimeoutSeconds key follows the same rule (Get-PkJobTimeLimit). + # batch: keep the two in step. NaN and +Infinity pass a `-lt 0` test and + # acted as no limit. A job's own TimeoutSeconds key follows the same rule + # (Get-PkJobTimeLimit). if ([double]::IsNaN($pkTimeoutSeconds) -or [double]::IsInfinity($pkTimeoutSeconds) -or $pkTimeoutSeconds -lt 0) { throw ("Invoke-PkProcessDispatch: -TimeoutSeconds must be a number of seconds, 0 (no limit) or more (got " + $pkTimeoutSeconds + ").") } @@ -2127,9 +2133,9 @@ function Invoke-PkProcessDispatch { # job as OutputWaitMs, so a Complete-PkProcess given no -StreamTimeoutMs # of its own waits only what's left of it (nothing). After an abort's # wait the final pass sets OutputWaitOver: it takes what has arrived. - # A closure, for $pkStreamTimeoutMs: a callback here only sees this - # frame's variables through dynamic scope, which a user's own - # variables could shadow. + # A closure, so it carries this call's $pkStreamTimeoutMs itself + # rather than finding it by dynamic scope (measured: no slower per + # job than the plain block on 5.1 or 7). $pkJobPollCompleted = { param($pkJob) if (-not $pkJob['Proc'].HasExited) { return $false } @@ -2756,6 +2762,8 @@ function Invoke-PkProcessBatch { [int]$AbortTimeoutSeconds = 60, [double]$TimeoutSeconds = 0, $OutputEncoding = $null, + # Complete-PkProcess's and Invoke-PkProcessDispatch's -StreamTimeoutMs + # default to the same 15000: keep the three in step. [int]$StreamTimeoutMs = 15000 ) # pk-prefixed, parameters included: inside a worker runspace the kit isn't