Skip to content

Commit e09dfd5

Browse files
santisqsantisq
committed
updating docs
1 parent dcae6cd commit e09dfd5

File tree

3 files changed

+270
-3
lines changed

3 files changed

+270
-3
lines changed

‎docs/Invoke-Parallel.md

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
---
2+
external help file: PSParallelPipeline-help.xml
3+
Module Name: PSParallelPipeline
4+
online version: https://github.com/santisq/PSParallelPipeline
5+
schema: 2.0.0
6+
---
7+
8+
# Invoke-Parallel
9+
10+
## SYNOPSIS
11+
Enables parallel processing of pipeline input objects.
12+
13+
## SYNTAX
14+
15+
```
16+
Invoke-Parallel [-ScriptBlock] <ScriptBlock> [-InputObject <Object>] [-ThrottleLimit <Int32>]
17+
[-TimeOutSeconds <Int32>] [-Variables <Hashtable>] [-Functions <String[]>] [-UseNewRunspace]
18+
[-ProgressAction <ActionPreference>] [<CommonParameters>]
19+
```
20+
21+
## DESCRIPTION
22+
\`Invoke-Parallel\` is a PowerShell function that allows parallel processing of input objects with similar capabilities as \`ForEach-Object\` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object)with its \`-Parallel\` parameter.
23+
24+
This function is mostly intended for users of Windows PowerShell 5.1 though fully compatible with newer versions of PowerShell.
25+
26+
## EXAMPLES
27+
28+
### Example 1: Run slow script in parallel batches
29+
```
30+
$message = 'Hello world from {0}'
31+
32+
0..10 | Invoke-Parallel {
33+
$using:message -f [runspace]::DefaultRunspace.InstanceId
34+
Start-Sleep 3
35+
} -ThrottleLimit 3
36+
```
37+
38+
### Example 2: Demonstrates how `-Variables` parameter works
39+
```
40+
$message = 'Hello world from {0}'
41+
42+
0..10 | Invoke-Parallel {
43+
$message -f [runspace]::DefaultRunspace.InstanceId
44+
Start-Sleep 3
45+
} -Variables @{ message = $message } -ThrottleLimit 3
46+
```
47+
48+
The \`-Variables\` parameter allows to pass variables to the parallel runspaces.
49+
The hash table \`Keys\` become the Variable Name inside the Script Block.
50+
51+
### Example 3: Adding to a single thread safe instance
52+
```
53+
$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new()
54+
55+
Get-Process | Invoke-Parallel {
56+
$dict = $using:threadSafeDictionary
57+
$dict.TryAdd($_.ProcessName, $_)
58+
}
59+
60+
$threadSafeDictionary["pwsh"]
61+
```
62+
63+
### Example 4: Adding to a single thread safe instance using `-Variables` parameter
64+
```
65+
$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new()
66+
67+
Get-Process | Invoke-Parallel {
68+
$dict.TryAdd($_.ProcessName, $_)
69+
} -Variables @{ dict = $threadSafeDictionary }
70+
71+
$threadSafeDictionary["pwsh"]
72+
```
73+
74+
### Example 5: Passing a locally defined Function to the parallel scope
75+
```
76+
function Greet { param($s) "$s hey there!" }
77+
78+
0..10 | Invoke-Parallel { Greet $_ } -Functions Greet
79+
```
80+
81+
This example demonstrates how to pass a locally defined Function to the Runspaces scope.
82+
83+
### Example 6: Setting a timeout for parallel tasks
84+
```
85+
Get-Process | Invoke-Parallel {
86+
Get-Random -Maximum 4 | Start-Sleep
87+
$_
88+
} -ThrottleLimit 10 -TimeoutSeconds 4
89+
```
90+
91+
If the timeout in seconds is reached all parallel invocations are stopped.
92+
93+
### Example 7: Using a new runspace for each invocation
94+
```
95+
0..5 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId }
96+
97+
Guid
98+
----
99+
ca9e3ff2-1eb0-4911-a288-838574fc7cb2
100+
775c65bd-5267-4ecb-943c-a1a1788d1116
101+
0cffb831-8e41-44b6-9ad8-5c9acfca64ce
102+
e5bc6cce-6cab-4d44-83e5-d947ab56ca15
103+
b7a9ba07-ad6d-4097-9224-3d87c10c01d7
104+
ca9e3ff2-1eb0-4911-a288-838574fc7cb2
105+
106+
0..5 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId } -UseNewRunspace
107+
108+
Guid
109+
----
110+
e4047803-0ee7-43e3-b195-c5a456db0cee
111+
3344f9f5-7b02-4926-b69e-313830cf4ee2
112+
ac22866a-7a41-4c24-b31c-47155054022f
113+
d5be0085-6f80-49c6-9a31-e50f1960329d
114+
80405d89-87fb-47f0-b6ba-a59392a99b6f
115+
3b78d3de-5759-4364-85df-dc72427e6af8
116+
```
117+
118+
By default the runspaces are reused.
119+
When the \`-UseNewRunspace\` parameter is used each parallel invocation will create a new runspace.
120+
121+
## PARAMETERS
122+
123+
### -Functions
124+
Existing functions in the Local Session to have available in the Script Block (Runspaces).
125+
126+
```yaml
127+
Type: String[]
128+
Parameter Sets: (All)
129+
Aliases: funcs
130+
131+
Required: False
132+
Position: Named
133+
Default value: None
134+
Accept pipeline input: False
135+
Accept wildcard characters: False
136+
```
137+
138+
### -InputObject
139+
Specifies the input objects to be processed in the ScriptBlock.
140+
141+
\> \[!NOTE\] \> This parameter is intended to be bound from pipeline.
142+
143+
```yaml
144+
Type: Object
145+
Parameter Sets: (All)
146+
Aliases:
147+
148+
Required: False
149+
Position: Named
150+
Default value: None
151+
Accept pipeline input: True (ByValue)
152+
Accept wildcard characters: False
153+
```
154+
155+
### -ScriptBlock
156+
Specifies the operation that is performed on each input object.
157+
This script block is run for every object in the pipeline.
158+
159+
```yaml
160+
Type: ScriptBlock
161+
Parameter Sets: (All)
162+
Aliases:
163+
164+
Required: True
165+
Position: 1
166+
Default value: None
167+
Accept pipeline input: False
168+
Accept wildcard characters: False
169+
```
170+
171+
### -ThrottleLimit
172+
Specifies the number of script blocks that are invoked in parallel.
173+
Input objects are blocked until the running script block count falls below the ThrottleLimit.
174+
175+
\> \[!NOTE\] \> \`-ThrottleLimit\` default value is \`5\`.
176+
177+
```yaml
178+
Type: Int32
179+
Parameter Sets: (All)
180+
Aliases: tl
181+
182+
Required: False
183+
Position: Named
184+
Default value: 5
185+
Accept pipeline input: False
186+
Accept wildcard characters: False
187+
```
188+
189+
### -UseNewRunspace
190+
Uses a new runspace for each parallel invocation instead of reusing them.
191+
192+
```yaml
193+
Type: SwitchParameter
194+
Parameter Sets: (All)
195+
Aliases: unr
196+
197+
Required: False
198+
Position: Named
199+
Default value: False
200+
Accept pipeline input: False
201+
Accept wildcard characters: False
202+
```
203+
204+
### -Variables
205+
Specifies a hash table of variables to have available in the Script Block (Runspaces).
206+
The hash table \`Keys\` become the Variable Name inside the Script Block.
207+
208+
```yaml
209+
Type: Hashtable
210+
Parameter Sets: (All)
211+
Aliases: vars
212+
213+
Required: False
214+
Position: Named
215+
Default value: None
216+
Accept pipeline input: False
217+
Accept wildcard characters: False
218+
```
219+
220+
### -ProgressAction
221+
{{ Fill ProgressAction Description }}
222+
223+
```yaml
224+
Type: ActionPreference
225+
Parameter Sets: (All)
226+
Aliases: proga
227+
228+
Required: False
229+
Position: Named
230+
Default value: None
231+
Accept pipeline input: False
232+
Accept wildcard characters: False
233+
```
234+
235+
### -TimeOutSeconds
236+
Specifies the number of seconds to wait for all input to be processed in parallel.
237+
After the specified timeout time, all running scripts are stopped and any remaining input objects to be processed are ignored.
238+
239+
```yaml
240+
Type: Int32
241+
Parameter Sets: (All)
242+
Aliases: to
243+
244+
Required: False
245+
Position: Named
246+
Default value: 0
247+
Accept pipeline input: False
248+
Accept wildcard characters: False
249+
```
250+
251+
### CommonParameters
252+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
253+
254+
## INPUTS
255+
256+
### Object
257+
You can pipe any object to this cmdlet.
258+
259+
## OUTPUTS
260+
261+
### Object
262+
This cmdlet returns objects that are determined by the input.
263+
264+
## NOTES
265+
266+
## RELATED LINKS

‎docs/en-US/Invoke-Parallel.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ schema: 2.0.0
99

1010
## SYNOPSIS
1111

12-
Enables parallel processing of pipeline input objects.
12+
Parallel processing of pipeline input objects.
1313

1414
## SYNTAX
1515

@@ -27,8 +27,8 @@ Invoke-Parallel
2727

2828
## DESCRIPTION
2929

30-
`Invoke-Parallel` is a PowerShell function that allows parallel processing of input objects with similar capabilities as
31-
[`ForEach-Object`](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object) with its `-Parallel` parameter.
30+
`Invoke-Parallel` is a PowerShell cmdlet that allows parallel processing of input objects with similar capabilities as
31+
[`ForEach-Object -Parallel`](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object).
3232

3333
This function is mostly intended for users of Windows PowerShell 5.1 though fully compatible with newer versions of PowerShell.
3434

‎module/PSParallelPipeline.psd1

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@
9898
'runspace'
9999
'parallel-processing'
100100
'powershell'
101+
'multithreading'
101102
)
102103

103104
# A URL to the license for this module.

0 commit comments

Comments
 (0)