PSQueue.psm1
|
#Region '.\prefix.ps1' -1 # The content of this file will be prepended to the top of the psm1 module file. This is useful for custom module setup is needed on import. #EndRegion '.\prefix.ps1' 2 #Region '.\Classes\class.extendedqueue.ps1' -1 <#PSScriptInfo { "CREATEDDATE": "2021-04-03", "COPYRIGHT": "(c) 2021, Hannes Palmquist, All Rights Reserved", "GUID": "ac27ffe4-e106-449f-9742-9f64b72af305", "COMPANYNAME": "Personal", "Version": "1.0.0.0", "FILENAME": "class.extendedqueue.ps1", "AUTHOR": "Hannes Palmquist", "AUTHOREMAIL": "hannes.palmquist@outlook.com" } PSScriptInfo#> class ExtendedQueue { [System.Collections.Queue]$Queue [system.collections.Generic.Queue[pscustomobject]]$LastOperations [int64]$TotalItemsAdded [int64]$TotalItemsRemoved [double]$AddPerSec [double]$RemovePerSec [double]$Velocity [int]$PerformanceHistory [void]AddQueueItem ( $Item ) { $this.Queue.Enqueue($item) $this.LastOperations.Enqueue(([pscustomobject]@{Type = 'Add'; TimeStamp = ([datetime]::Now) })) $this.TotalItemsAdded++ $this.CalculateSpeed() } [psobject]GetNextQueueItem() { try { $ReturnObject = $this.Queue.Dequeue() $this.LastOperations.Enqueue(([pscustomobject]@{Type = 'Remove'; TimeStamp = ([datetime]::Now) })) $this.TotalItemsRemoved++ } catch { $ReturnObject = $null } $this.CalculateSpeed() return $ReturnObject } [psobject]ShowNextQueueItem() { return $this.Queue.Peek() } [int64]GetQueueCount() { return $this.Queue.Count } [void]ClearAllQueueItems() { $this.Queue.Clear() } [array]GetAllQueueItems() { $Result = while ($this.GetQueueCount()) { $this.GetNextQueueItem() $this.TotalItemsRemoved++ } $this.CalculateSpeed() return $Result } [void]RotateLastOperations ($CurrentTime) { while ($this.LastOperations.Count -ge $this.PerformanceHistory) { $null = $this.LastOperations.Dequeue() } } [void]CalculateSpeed () { $CurrentTime = [datetime]::Now $this.RotateLastOperations($CurrentTime) $ItemsAdded = $this.LastOperations.Where( { $PSItem.Type -eq 'Add' }).Count $ItemsRemoved = $this.LastOperations.Where( { $PSItem.Type -eq 'Remove' }).Count try { $this.AddPerSec = $ItemsAdded / ($CurrentTime - $this.LastOperations.Where( { $PSItem.Type -eq 'Add' })[0].TimeStamp).TotalSeconds } catch { $this.AddPerSec = 0 } try { $this.RemovePerSec = $ItemsRemoved / ($CurrentTime - $this.LastOperations.Where( { $PSItem.Type -eq 'Remove' })[0].TimeStamp).TotalSeconds } catch { $this.RemovePerSec = 0 } $this.Velocity = $this.AddPerSec - $this.RemovePerSec } ExtendedQueue () { $this.Queue = [System.Collections.Queue]::New() $this.LastOperations = [system.collections.Generic.Queue[pscustomobject]]::New() $this.TotalItemsAdded = 0 $this.TotalItemsRemoved = 0 $this.AddPerSec = 0 $this.RemovePerSec = 0 $this.PerformanceHistory = 50 } } #EndRegion '.\Classes\class.extendedqueue.ps1' 103 #Region '.\Private\Assert-FolderExist.ps1' -1 function Assert-FolderExist { <# .SYNOPSIS Verify and create folder .DESCRIPTION Verifies that a folder path exists, if not it will create it .PARAMETER Path Defines the path to be validated .EXAMPLE 'C:\Temp' | Assert-FolderExist This will verify that the path exists and if it does not the folder will be created #> [CmdletBinding()] param( [Parameter(Mandatory, ValueFromPipeline)] [string] $Path ) process { $exists = Test-Path -Path $Path -PathType Container if (!$exists) { $null = New-Item -Path $Path -ItemType Directory } } } #EndRegion '.\Private\Assert-FolderExist.ps1' 31 #Region '.\Private\Invoke-GarbageCollect.ps1' -1 function Invoke-GarbageCollect { <# .SYNOPSIS Calls system.gc collect method. Purpose is mainly for readability. .DESCRIPTION Calls system.gc collect method. Purpose is mainly for readability. .EXAMPLE Invoke-GarbageCollect #> [system.gc]::Collect() } #EndRegion '.\Private\Invoke-GarbageCollect.ps1' 13 #Region '.\Private\pslog.ps1' -1 function pslog { <# .SYNOPSIS This is simple logging function that automatically log to file. Logging to console is maintained. .DESCRIPTION This is simple logging function that automatically log to file. Logging to console is maintained. .PARAMETER Severity Defines the type of log, valid vales are, Success,Info,Warning,Error,Verbose,Debug .PARAMETER Message Defines the message for the log entry .PARAMETER Source Defines a source, this is useful to separate log entries in categories for different stages of a process or for each function, defaults to default .PARAMETER Throw Specifies that when using severity error pslog will throw. This is useful in catch statements so that the terminating error is propagated upwards in the stack. .PARAMETER LogDirectoryOverride Defines a hardcoded log directory to write the log file to. This defaults to %appdatalocal%\<modulename\logs. .PARAMETER DoNotLogToConsole Specifies that logs should only be written to the log file and not to the console. .EXAMPLE pslog Verbose 'Successfully wrote to logfile' Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Sole purpose of function is logging, including console')] [cmdletbinding()] param( [parameter(Position = 0)] [ValidateSet('Success', 'Info', 'Warning', 'Error', 'Verbose', 'Debug')] [Alias('Type')] [string] $Severity, [parameter(Mandatory, Position = 1)] [string] $Message, [parameter(position = 2)] [string] $source = 'default', [parameter(Position = 3)] [switch] $Throw, [parameter(Position = 4)] [string] $LogDirectoryOverride, [parameter(Position = 5)] [switch] $DoNotLogToConsole ) begin { if (-not $LogDirectoryOverride) { $localappdatapath = [Environment]::GetFolderPath('localapplicationdata') # ie C:\Users\<username>\AppData\Local $modulename = $MyInvocation.MyCommand.Module $logdir = "$localappdatapath\$modulename\logs" } else { $logdir = $LogDirectoryOverride } $logdir | Assert-FolderExist -Verbose:$VerbosePreference $timestamp = (Get-Date) $logfilename = ('{0}.log' -f $timestamp.ToString('yyy-MM-dd')) $timestampstring = $timestamp.ToString('yyyy-MM-ddThh:mm:ss.ffffzzz') } process { switch ($Severity) { 'Success' { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false if (-not $DoNotLogToConsole) { Write-Host -Object "SUCCESS: $timestampstring`t$source`t$message" -ForegroundColor Green } } 'Info' { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false if (-not $DoNotLogToConsole) { Write-Information -MessageData "$timestampstring`t$source`t$message" } } 'Warning' { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false if (-not $DoNotLogToConsole) { Write-Warning -Message "$timestampstring`t$source`t$message" } } 'Error' { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false if (-not $DoNotLogToConsole) { Write-Error -Message "$timestampstring`t$source`t$message" } if ($throw) { throw } } 'Verbose' { if ($VerbosePreference -ne 'SilentlyContinue') { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false } if (-not $DoNotLogToConsole) { Write-Verbose -Message "$timestampstring`t$source`t$message" } } 'Debug' { if ($DebugPreference -ne 'SilentlyContinue') { "$timestampstring`t$psitem`t$source`t$message" | Add-Content -Path "$logdir\$logfilename" -Encoding utf8 -WhatIf:$false } if (-not $DoNotLogToConsole) { Write-Debug -Message "$timestampstring`t$source`t$message" } } } } } #EndRegion '.\Private\pslog.ps1' 137 #Region '.\Private\Write-PSProgress.ps1' -1 function Write-PSProgress { <# .SYNOPSIS Wrapper for PSProgress .DESCRIPTION This function will automatically calculate items/sec, eta, time remaining as well as set the update frequency in case the there are a lot of items processing fast. .PARAMETER Activity Defines the activity name for the progressbar .PARAMETER Id Defines a unique ID for this progressbar, this is used when nesting progressbars .PARAMETER Target Defines a arbitrary text for the currently processed item .PARAMETER ParentId Defines the ID of a parent progress bar .PARAMETER Completed Explicitly tells powershell to set the progress bar as completed removing it from view. In some cases the progress bar will linger if this is not done. .PARAMETER Counter The currently processed items counter .PARAMETER Total The total number of items to process .PARAMETER StartTime Sets the start datetime for the progressbar, this is required to calculate items/sec, eta and time remaining .PARAMETER DisableDynamicUpdateFrquency Disables the dynamic update frequency function and every item will update the status of the progressbar .PARAMETER NoTimeStats Disables calculation of items/sec, eta and time remaining .EXAMPLE 1..10000 | foreach-object -begin {$StartTime = Get-Date} -process { Write-PSProgress -Activity 'Looping' -Target $PSItem -Counter $PSItem -Total 10000 -StartTime $StartTime } Explanation of the function or its result. You can include multiple examples with additional .EXAMPLE lines #> [CmdletBinding()] param( [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Standard')] [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'Completed')] [string] $Activity, [Parameter(Position = 1, ParameterSetName = 'Standard')] [Parameter(Position = 1, ParameterSetName = 'Completed')] [ValidateRange(0, 2147483647)] [int] $Id, [Parameter(Position = 2, ParameterSetName = 'Standard')] [string] $Target, [Parameter(Position = 3, ParameterSetName = 'Standard')] [Parameter(Position = 3, ParameterSetName = 'Completed')] [ValidateRange(-1, 2147483647)] [int] $ParentId, [Parameter(Position = 4, ParameterSetname = 'Completed')] [switch] $Completed, [Parameter(Mandatory = $true, Position = 5, ParameterSetName = 'Standard')] [long] $Counter, [Parameter(Mandatory = $true, Position = 6, ParameterSetName = 'Standard')] [long] $Total, [Parameter(Position = 7, ParameterSetName = 'Standard')] [datetime] $StartTime, [Parameter(Position = 8, ParameterSetName = 'Standard')] [switch] $DisableDynamicUpdateFrquency, [Parameter(Position = 9, ParameterSetName = 'Standard')] [switch] $NoTimeStats ) # Define current timestamp $TimeStamp = (Get-Date) # Define a dynamic variable name for the global starttime variable $StartTimeVariableName = ('ProgressStartTime_{0}' -f $Activity.Replace(' ', '')) # Manage global start time variable if ($PSBoundParameters.ContainsKey('Completed') -and (Get-Variable -Name $StartTimeVariableName -Scope Global -ErrorAction SilentlyContinue)) { # Remove the global starttime variable if the Completed switch parameter is users try { Remove-Variable -Name $StartTimeVariableName -ErrorAction Stop -Scope Global } catch { throw $_ } } elseif (-not (Get-Variable -Name $StartTimeVariableName -Scope Global -ErrorAction SilentlyContinue)) { # Global variable do not exist, create global variable if ($null -eq $StartTime) { # No start time defined with parameter, use current timestamp as starttime Set-Variable -Name $StartTimeVariableName -Value $TimeStamp -Scope Global $StartTime = $TimeStamp } else { # Start time defined with parameter, use that value as starttime Set-Variable -Name $StartTimeVariableName -Value $StartTime -Scope Global } } else { # Global start time variable is defined, collect and use it $StartTime = Get-Variable -Name $StartTimeVariableName -Scope Global -ErrorAction Stop -ValueOnly } # Define frequency threshold $Frequency = [Math]::Ceiling($Total / 100) switch ($PSCmdlet.ParameterSetName) { 'Standard' { # Only update progress is any of the following is true # - DynamicUpdateFrequency is disabled # - Counter matches a mod of defined frequecy # - Counter is 0 # - Counter is equal to Total (completed) if (($DisableDynamicUpdateFrquency) -or ($Counter % $Frequency -eq 0) -or ($Counter -eq 1) -or ($Counter -eq $Total)) { # Calculations for both timestats and without $Percent = [Math]::Round(($Counter / $Total * 100), 0) # Define count progress string status $CountProgress = ('{0}/{1}' -f $Counter, $Total) # If percent would turn out to be more than 100 due to incorrect total assignment revert back to 100% to avoid that write-progress throws if ($Percent -gt 100) { $Percent = 100 } # Define write-progress splat hash $WriteProgressSplat = @{ Activity = $Activity PercentComplete = $Percent CurrentOperation = $Target } # Add ID if specified if ($Id) { $WriteProgressSplat.Id = $Id } # Add ParentID if specified if ($ParentId) { $WriteProgressSplat.ParentId = $ParentId } # Calculations for either timestats and without if ($NoTimeStats) { $WriteProgressSplat.Status = ('{0} - {1}%' -f $CountProgress, $Percent) } else { # Total seconds elapsed since start $TotalSeconds = ($TimeStamp - $StartTime).TotalSeconds # Calculate items per sec processed (IpS) $ItemsPerSecond = ([Math]::Round(($Counter / $TotalSeconds), 2)) # Calculate seconds spent per processed item (for ETA) $SecondsPerItem = if ($Counter -eq 0) { 0 } else { ($TotalSeconds / $Counter) } # Calculate seconds remainging $SecondsRemaing = ($Total - $Counter) * $SecondsPerItem $WriteProgressSplat.SecondsRemaining = $SecondsRemaing # Calculate ETA $ETA = $(($Timestamp).AddSeconds($SecondsRemaing).ToShortTimeString()) # Add findings to write-progress splat hash $WriteProgressSplat.Status = ('{0} - {1}% - ETA: {2} - IpS {3}' -f $CountProgress, $Percent, $ETA, $ItemsPerSecond) } # Call writeprogress Write-Progress @WriteProgressSplat } } 'Completed' { Write-Progress -Activity $Activity -Id $Id -Completed } } } #EndRegion '.\Private\Write-PSProgress.ps1' 214 #Region '.\Public\Add-QueueItem.ps1' -1 function Add-QueueItem { <# .DESCRIPTION Adds a new item to the queue .PARAMETER Queue Queue object to add items to .PARAMETER Items Defines the items to add to the queue .EXAMPLE Add-QueueItem -Queue $Queue -Item 'Foo' This example shows how to add an item to the queue #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '', Justification = 'False positive')] [CmdletBinding()] param( [parameter(Mandatory)][ExtendedQueue]$Queue, [parameter(Mandatory, ValueFromPipeline)][object[]]$Items ) process { $Items | ForEach-Object { $Queue.AddQueueItem($PSItem) } } } #EndRegion '.\Public\Add-QueueItem.ps1' 28 #Region '.\Public\Clear-AllQueueItems.ps1' -1 function Clear-AllQueueItems { <# .DESCRIPTION Discard all queued items in queue .PARAMETER Queue Queue object to discard all items in .EXAMPLE Clear-AllQueueItems -Queue $Queue This example shows how to discard all items of the provided queue #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'Sole purpose of function to target multiple items')] [CmdletBinding()] param( [parameter(Mandatory)][ExtendedQueue]$Queue ) $Queue.ClearAllQueueItems() } #EndRegion '.\Public\Clear-AllQueueItems.ps1' 21 #Region '.\Public\Get-AllQueueItems.ps1' -1 function Get-AllQueueItems { <# .DESCRIPTION Collect all remaining queue items .PARAMETER Queue Queue object to discard all items in .EXAMPLE Get-AllQueueItems -Queue $Queue This example how to retreive all queue items remaining in the queue #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'Sole purpose of function to target multiple items')] [CmdletBinding()] param( [parameter(Mandatory)][ExtendedQueue]$Queue ) $Queue.GetAllQueuedItems() } #EndRegion '.\Public\Get-AllQueueItems.ps1' 21 #Region '.\Public\Get-NextQueueItem.ps1' -1 function Get-NextQueueItem { <# .DESCRIPTION Returns the next object from queue. That object will be removed from the queue. .PARAMETER Queue Queue object to retreive next items from .EXAMPLE Get-NextQueueItem -Queue $Queue This example with return the next item in queue. #> [CmdletBinding()] param( [parameter(Mandatory)][ExtendedQueue]$Queue ) return $Queue.GetNextQueueItem() } #EndRegion '.\Public\Get-NextQueueItem.ps1' 21 #Region '.\Public\Initialize-Queue.ps1' -1 function Initialize-Queue { <# .DESCRIPTION This cmdlet initializes a new queue object. The returned object is a wrapper class for the System.Collection.Queue class. This class (ExtendedQueue) provides additional functionality compared to the standard Queue class. The Queue object is stored as a property of the returned object called "Queue". The object returned also contains properties containing counts of added items, removed items, additions per sec, removes per sec and velocity (delta between add & remove per sec.). The module cmdlet Measure-Queue returns these metrics. .EXAMPLE $Queue = Initialize-Queue This example will create a new instance of the queue object #> [CmdletBinding()] param( ) return ([ExtendedQueue]::new()) } #endregion #EndRegion '.\Public\Initialize-Queue.ps1' 25 #Region '.\Public\Measure-Queue.ps1' -1 function Measure-Queue { <# .DESCRIPTION Returns an object with performance metrics for the provided queue. .PARAMETER Queue Queue object to retreive performance metrics for. .EXAMPLE Measure-Queue -Queue $Queue This example will return a object containing performance metrics for the provided queue. #> [CmdletBinding()] # Enabled advanced function support param( [parameter(Mandatory)][ExtendedQueue]$Queue ) return [pscustomobject]@{ QueueCount = $Queue.GetQueueCount() AddsPerSec = [Math]::Round($Queue.AddPerSec, 2) RemovesPerSec = [Math]::Round($Queue.RemovePerSec, 2) Velocity = [Math]::Round($Queue.Velocity, 2) } } #EndRegion '.\Public\Measure-Queue.ps1' 26 #Region '.\Public\Show-NextQueueItem.ps1' -1 function Show-NextQueueItem { <# .DESCRIPTION Shows the next item in queue without removing it from queue. .PARAMETER Queue Queue object to retreive performance metrics for. .EXAMPLE Show-NextQueueItem Description of example #> [CmdletBinding()] # Enabled advanced function support param( [parameter(Mandatory)][ExtendedQueue]$Queue ) return $Queue.ShowNextQueueItem() } #EndRegion '.\Public\Show-NextQueueItem.ps1' 21 #Region '.\suffix.ps1' -1 # The content of this file will be appended to the top of the psm1 module file. This is useful for custom procesedures after all module functions are loaded. #EndRegion '.\suffix.ps1' 2 |