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>Enables parallel processing of pipeline input objects.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>`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.</maml:para> <maml:para>This function is mostly intended for users of Windows PowerShell 5.1 though fully compatible with newer versions of PowerShell.</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="1" 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="none"> <maml:name>Functions</maml:name> <maml:description> <maml:para>Existing functions in the Local Session to have available in the Script Block (Runspaces).</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="none"> <maml:name>ThrottleLimit</maml:name> <maml:description> <maml:para>Specifies the number of script blocks that are invoked in parallel. 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="none"> <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: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="none"> <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="none"> <maml:name>Variables</maml:name> <maml:description> <maml:para>Specifies a hash table of variables to have available in the Script Block (Runspaces). The hash table `Keys` become the Variable Name inside the Script Block.</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="none"> <maml:name>Functions</maml:name> <maml:description> <maml:para>Existing functions in the Local Session to have available in the Script Block (Runspaces).</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="1" 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="none"> <maml:name>ThrottleLimit</maml:name> <maml:description> <maml:para>Specifies the number of script blocks that are invoked in parallel. 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="none"> <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: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="none"> <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="none"> <maml:name>Variables</maml:name> <maml:description> <maml:para>Specifies a hash table of variables to have available in the Script Block (Runspaces). The hash table `Keys` become the Variable Name inside the Script Block.</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 input.</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}' 0..10 | Invoke-Parallel { $using:message -f [runspace]::DefaultRunspace.InstanceId Start-Sleep 3 } -ThrottleLimit 3</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 2: Demonstrates how `-Variables` parameter works ---</maml:title> <dev:code>$message = 'Hello world from {0}' 0..10 | Invoke-Parallel { $message -f [runspace]::DefaultRunspace.InstanceId Start-Sleep 3 } -Variables @{ message = $message } -ThrottleLimit 3</dev:code> <dev:remarks> <maml:para>The `-Variables` parameter allows to pass variables to the parallel runspaces. The hash table `Keys` become the Variable Name inside the Script Block.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 3: Adding to a single thread safe instance ------</maml:title> <dev:code>$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new() Get-Process | Invoke-Parallel { $dict = $using:threadSafeDictionary $dict.TryAdd($_.ProcessName, $_) } $threadSafeDictionary["pwsh"]</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` parameter</maml:title> <dev:code>$threadSafeDictionary = [System.Collections.Concurrent.ConcurrentDictionary[string,object]]::new() Get-Process | Invoke-Parallel { $dict.TryAdd($_.ProcessName, $_) } -Variables @{ dict = $threadSafeDictionary } $threadSafeDictionary["pwsh"]</dev:code> <dev:remarks> <maml:para></maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 5: Passing a locally defined Function to the parallel scope</maml:title> <dev:code>function Greet { param($s) "$s hey there!" } 0..10 | Invoke-Parallel { Greet $_ } -Functions Greet</dev:code> <dev:remarks> <maml:para>This example demonstrates how to pass a locally defined Function to the Runspaces scope.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 6: Setting a timeout for parallel tasks -------</maml:title> <dev:code>Get-Process | Invoke-Parallel { Get-Random -Maximum 4 | Start-Sleep $_ } -ThrottleLimit 10 -TimeoutSeconds 4</dev:code> <dev:remarks> <maml:para>If the timeout in seconds is reached all parallel invocations are stopped.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 7: Using a new runspace for each invocation -----</maml:title> <dev:code>0..5 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId } Guid ---- ca9e3ff2-1eb0-4911-a288-838574fc7cb2 775c65bd-5267-4ecb-943c-a1a1788d1116 0cffb831-8e41-44b6-9ad8-5c9acfca64ce e5bc6cce-6cab-4d44-83e5-d947ab56ca15 b7a9ba07-ad6d-4097-9224-3d87c10c01d7 ca9e3ff2-1eb0-4911-a288-838574fc7cb2 0..5 | Invoke-Parallel { [runspace]::DefaultRunspace.InstanceId } -UseNewRunspace Guid ---- e4047803-0ee7-43e3-b195-c5a456db0cee 3344f9f5-7b02-4926-b69e-313830cf4ee2 ac22866a-7a41-4c24-b31c-47155054022f d5be0085-6f80-49c6-9a31-e50f1960329d 80405d89-87fb-47f0-b6ba-a59392a99b6f 3b78d3de-5759-4364-85df-dc72427e6af8</dev:code> <dev:remarks> <maml:para>By default the runspaces are reused. When the `-UseNewRunspace` parameter is used each parallel invocation will create a new runspace.</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> |