en-US/PSParallelPipeline-help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-Parallel</command:name> <command:verb>Invoke</command:verb> <command:noun>Parallel</command:noun> <maml:description> <maml:para>Parallel processing of pipeline input objects.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>`Invoke-Parallel` is a PowerShell cmdlet that allows parallel processing of input objects with similar capabilities as `ForEach-Object -Parallel` (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object)introduced in PowerShell v7.0.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Parallel</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>ScriptBlock</maml:name> <maml:description> <maml:para>Specifies the operation that is performed on each input object. This script block is run for every object in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="funcs"> <maml:name>Functions</maml:name> <maml:description> <maml:para>Specifies existing functions in the Local Session to have added to the runspaces Initial Session State (https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.initialsessionstate).</maml:para> <maml:para>> [!TIP] > > This method is the recommended way of passing-in local functions to the parallel scope. The alternative to this method is passing-in the function definition (as a string) to the parallel scope and define the function in it.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the input objects to be processed in the ScriptBlock.</maml:para> <maml:para>> [!NOTE] > > This parameter is intended to be bound from pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="tl"> <maml:name>ThrottleLimit</maml:name> <maml:description> <maml:para>Specifies the number of script blocks that are invoked in parallel (Degree of Parallelism). Input objects are blocked until the running script block count falls below the ThrottleLimit.</maml:para> <maml:para>> [!NOTE] > > `-ThrottleLimit` default value is `5`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>5</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="to"> <maml:name>TimeoutSeconds</maml:name> <maml:description> <maml:para>Specifies the number of seconds to wait for all input to be processed in parallel. After the specified timeout time, all running scripts are stopped and any remaining input objects to be processed are ignored.</maml:para> <maml:para>> [!NOTE] > > Default value of `0` disables the timeout and the cmdlet runs until all pipeline input is processed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="unr"> <maml:name>UseNewRunspace</maml:name> <maml:description> <maml:para>Uses a new runspace for each parallel invocation instead of reusing them.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="vars"> <maml:name>Variables</maml:name> <maml:description> <maml:para>Specifies a hashtable of variables to have available in the parallel scope. The hashtable keys defines the name for passed-in variables.</maml:para> <maml:para>> [!TIP] > > This parameter is an alternative for the `$using:` scope modifier (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.4#scope-modifiers).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="funcs"> <maml:name>Functions</maml:name> <maml:description> <maml:para>Specifies existing functions in the Local Session to have added to the runspaces Initial Session State (https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.initialsessionstate).</maml:para> <maml:para>> [!TIP] > > This method is the recommended way of passing-in local functions to the parallel scope. The alternative to this method is passing-in the function definition (as a string) to the parallel scope and define the function in it.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>Specifies the input objects to be processed in the ScriptBlock.</maml:para> <maml:para>> [!NOTE] > > This parameter is intended to be bound from pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>ScriptBlock</maml:name> <maml:description> <maml:para>Specifies the operation that is performed on each input object. This script block is run for every object in the pipeline.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScriptBlock</command:parameterValue> <dev:type> <maml:name>ScriptBlock</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="tl"> <maml:name>ThrottleLimit</maml:name> <maml:description> <maml:para>Specifies the number of script blocks that are invoked in parallel (Degree of Parallelism). Input objects are blocked until the running script block count falls below the ThrottleLimit.</maml:para> <maml:para>> [!NOTE] > > `-ThrottleLimit` default value is `5`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>5</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="to"> <maml:name>TimeoutSeconds</maml:name> <maml:description> <maml:para>Specifies the number of seconds to wait for all input to be processed in parallel. After the specified timeout time, all running scripts are stopped and any remaining input objects to be processed are ignored.</maml:para> <maml:para>> [!NOTE] > > Default value of `0` disables the timeout and the cmdlet runs until all pipeline input is processed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>0</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="unr"> <maml:name>UseNewRunspace</maml:name> <maml:description> <maml:para>Uses a new runspace for each parallel invocation instead of reusing them.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="vars"> <maml:name>Variables</maml:name> <maml:description> <maml:para>Specifies a hashtable of variables to have available in the parallel scope. The hashtable keys defines the name for passed-in variables.</maml:para> <maml:para>> [!TIP] > > This parameter is an alternative for the `$using:` scope modifier (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_scopes?view=powershell-7.4#scope-modifiers).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Hashtable</command:parameterValue> <dev:type> <maml:name>Hashtable</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>Object</maml:name> </dev:type> <maml:description> <maml:para>You can pipe any object to this cmdlet.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Object</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet returns objects that are determined by the script block.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert /> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Run slow script in parallel batches --------</maml:title> <dev:code>$message = 'Hello world from ' 0..10 | Invoke-Parallel { $using:message + [runspace]::DefaultRunspace.InstanceId Start-Sleep 3 }</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 2: Demonstrates `-Variables` Parameter --------</maml:title> <dev:code>$message = 'Hello world from ' 0..10 | Invoke-Parallel { $message + [runspace]::DefaultRunspace.InstanceId Start-Sleep 3 } -Variables @{ message = $message }</dev:code> <dev:remarks> <maml:para>`-Variables` (#-variables)specifies a hashtable with key / value pairs of variables to pass-in to the parallel scope. The hashtable keys defines the name for passed-in variables. This parameter is an alternative for the `$using:` scope modifier.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Adding to a single thread safe instance with `$using:` scope modifier</maml:title> <dev:code>$dict = [System.Collections.Concurrent.ConcurrentDictionary[int, object]]::new() Get-Process | Invoke-Parallel { ($using:dict)[$_.Id] = $_ } $dict[$PID]</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4: Adding to a single thread safe instance using `-Variables`</maml:title> <dev:code>$dict = [System.Collections.Concurrent.ConcurrentDictionary[int, object]]::new() Get-Process | Invoke-Parallel { $dict[$_.Id] = $_ } -Variables @{ dict = $dict } $dict[$PID]</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 5: Demonstrates `-Functions` Parameter --------</maml:title> <dev:code>function Greet { param($s) "$s hey there!" } 0..10 | Invoke-Parallel { Greet $_ } -Functions Greet</dev:code> <dev:remarks> <maml:para>`-Functions` (#-functions) adds locally defined functions to the runspaces [Initial Session State](https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.runspaces.initialsessionstate)allowing you to use them in the parallel scope.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 6: Demonstrates `-TimeoutSeconds` Parameter -----</maml:title> <dev:code>0..10 | Invoke-Parallel { Start-Sleep 1 } -TimeoutSeconds 3</dev:code> <dev:remarks> <maml:para>All parallel invocations are stopped when the timeout is reached and any remaining input objects to be processed are ignored.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 7: Demonstrates `-UseNewRunspace` Parameter -----</maml:title> <dev:code>0..3 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId } -ThrottleLimit 2 # Guid # ---- # c945ae1f-4e66-4312-b23c-f3994965308e # 1c6af45c-8727-4488-937a-4dfc1d259e9e # c945ae1f-4e66-4312-b23c-f3994965308e # 1c6af45c-8727-4488-937a-4dfc1d259e9e 0..3 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId } -ThrottleLimit 2 -UseNewRunspace # Guid # ---- # 7a1c3871-6ce2-4b7f-ae90-fb1e92cd9678 # 2488be9e-15fe-4be2-882d-7d98b068c913 # d3dd7b5d-e7e3-457f-b6fb-def35fe837d7 # 9af7c222-061d-4c89-b073-375ee925e538</dev:code> <dev:remarks> <maml:para>By default the runspaces are reused. With `-UseNewRunspace` a new runspace is created per input object.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://github.com/santisq/PSParallelPipeline</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |