Public/Timers.ps1
|
<#
.SYNOPSIS Adds a new Timer with logic to periodically invoke. .DESCRIPTION Adds a new Timer with logic to periodically invoke, with options to only run a specific number of times. .PARAMETER Name The Name of the Timer. .PARAMETER Interval The number of seconds to periodically invoke the Timer's ScriptBlock. .PARAMETER ScriptBlock The script for the Timer. .PARAMETER Limit The number of times the Timer should be invoked before being removed. (If 0, it will run indefinitely) .PARAMETER Skip The number of "invokes" to skip before the Timer actually runs. .PARAMETER ArgumentList An array of arguments to supply to the Timer's ScriptBlock. .PARAMETER FilePath A literal, or relative, path to a file containing a ScriptBlock for the Timer's logic. .PARAMETER OnStart If supplied, the timer will trigger when the server starts. .EXAMPLE Add-PodeTimer -Name 'Hello' -Interval 10 -ScriptBlock { 'Hello, world!' | Out-Default } .EXAMPLE Add-PodeTimer -Name 'RunOnce' -Interval 1 -Limit 1 -ScriptBlock { /* logic */ } .EXAMPLE Add-PodeTimer -Name 'RunAfter60secs' -Interval 10 -Skip 6 -ScriptBlock { /* logic */ } .EXAMPLE Add-PodeTimer -Name 'Args' -Interval 2 -ScriptBlock { /* logic */ } -ArgumentList 'arg1', 'arg2' #> function Add-PodeTimer { [CmdletBinding(DefaultParameterSetName='Script')] param ( [Parameter(Mandatory=$true)] [string] $Name, [Parameter(Mandatory=$true)] [int] $Interval, [Parameter(Mandatory=$true, ParameterSetName='Script')] [scriptblock] $ScriptBlock, [Parameter()] [int] $Limit = 0, [Parameter()] [int] $Skip = 0, [Parameter(Mandatory=$true, ParameterSetName='File')] [string] $FilePath, [Parameter()] [object[]] $ArgumentList, [switch] $OnStart ) # error if serverless Test-PodeIsServerless -FunctionName 'Add-PodeTimer' -ThrowError # ensure the timer doesn't already exist if ($PodeContext.Timers.Items.ContainsKey($Name)) { throw "[Timer] $($Name): Timer already defined" } # is the interval valid? if ($Interval -le 0) { throw "[Timer] $($Name): Interval must be greater than 0" } # is the limit valid? if ($Limit -lt 0) { throw "[Timer] $($Name): Cannot have a negative limit" } # is the skip valid? if ($Skip -lt 0) { throw "[Timer] $($Name): Cannot have a negative skip value" } # if we have a file path supplied, load that path as a scriptblock if ($PSCmdlet.ParameterSetName -ieq 'file') { $ScriptBlock = Convert-PodeFileToScriptBlock -FilePath $FilePath } # check if the scriptblock has any using vars $ScriptBlock, $usingVars = Invoke-PodeUsingScriptConversion -ScriptBlock $ScriptBlock -PSSession $PSCmdlet.SessionState # check for state/session vars $ScriptBlock = Invoke-PodeStateScriptConversion -ScriptBlock $ScriptBlock $ScriptBlock = Invoke-PodeSessionScriptConversion -ScriptBlock $ScriptBlock # calculate the next tick time (based on Skip) $NextTriggerTime = [DateTime]::Now.AddSeconds($Interval) if ($Skip -gt 1) { $NextTriggerTime = $NextTriggerTime.AddSeconds($Interval * $Skip) } # add the timer $PodeContext.Timers.Enabled = $true $PodeContext.Timers.Items[$Name] = @{ Name = $Name Interval = $Interval Limit = $Limit Count = 0 Skip = $Skip NextTriggerTime = $NextTriggerTime LastTriggerTime = $null Script = $ScriptBlock UsingVariables = $usingVars Arguments = $ArgumentList OnStart = $OnStart Completed = $false } } <# .SYNOPSIS Adhoc invoke a Timer's logic. .DESCRIPTION Adhoc invoke a Timer's logic outside of its defined interval. This invocation doesn't count towards the Timer's limit. .PARAMETER Name The Name of the Timer. .PARAMETER ArgumentList An array of arguments to supply to the Timer's ScriptBlock. .EXAMPLE Invoke-PodeTimer -Name 'timer-name' #> function Invoke-PodeTimer { [CmdletBinding()] param( [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [string] $Name, [Parameter()] [object[]] $ArgumentList = $null ) # ensure the timer exists if (!$PodeContext.Timers.Items.ContainsKey($Name)) { throw "Timer '$($Name)' does not exist" } # run timer logic Invoke-PodeInternalTimer -Timer $PodeContext.Timers.Items[$Name] -ArgumentList $ArgumentList } <# .SYNOPSIS Removes a specific Timer. .DESCRIPTION Removes a specific Timer. .PARAMETER Name The Name of Timer to be removed. .EXAMPLE Remove-PodeTimer -Name 'SaveState' #> function Remove-PodeTimer { [CmdletBinding()] param ( [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [string] $Name ) $null = $PodeContext.Timers.Items.Remove($Name) } <# .SYNOPSIS Removes all Timers. .DESCRIPTION Removes all Timers. .EXAMPLE Clear-PodeTimers #> function Clear-PodeTimers { [CmdletBinding()] param() $PodeContext.Timers.Items.Clear() } <# .SYNOPSIS Edits an existing Timer. .DESCRIPTION Edits an existing Timer's properties, such as interval or scriptblock. .PARAMETER Name The Name of the Timer. .PARAMETER Interval The new Interval for the Timer in seconds. .PARAMETER ScriptBlock The new ScriptBlock for the Timer. .PARAMETER ArgumentList Any new Arguments for the Timer. .EXAMPLE Edit-PodeTimer -Name 'Hello' -Interval 10 #> function Edit-PodeTimer { [CmdletBinding()] param( [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [string] $Name, [Parameter()] [int] $Interval = 0, [Parameter()] [scriptblock] $ScriptBlock, [Parameter()] [object[]] $ArgumentList ) # ensure the timer exists if (!$PodeContext.Timers.Items.ContainsKey($Name)) { throw "Timer '$($Name)' does not exist" } $_timer = $PodeContext.Timers.Items[$Name] # edit interval if supplied if ($Interval -gt 0) { $_timer.Interval = $Interval } # edit scriptblock if supplied if (!(Test-PodeIsEmpty $ScriptBlock)) { $ScriptBlock, $usingVars = Invoke-PodeUsingScriptConversion -ScriptBlock $ScriptBlock -PSSession $PSCmdlet.SessionState $ScriptBlock = Invoke-PodeStateScriptConversion -ScriptBlock $ScriptBlock $ScriptBlock = Invoke-PodeSessionScriptConversion -ScriptBlock $ScriptBlock $_timer.Script = $ScriptBlock $_timer.UsingVariables = $usingVars } # edit arguments if supplied if (!(Test-PodeIsEmpty $ArgumentList)) { $_timer.Arguments = $ArgumentList } } <# .SYNOPSIS Returns any defined timers. .DESCRIPTION Returns any defined timers, with support for filtering. .PARAMETER Name Any timer Names to filter the timers. .EXAMPLE Get-PodeTimer .EXAMPLE Get-PodeTimer -Name Name1, Name2 #> function Get-PodeTimer { [CmdletBinding()] param( [Parameter()] [string[]] $Name ) $timers = $PodeContext.Timers.Items.Values # further filter by timer names if (($null -ne $Name) -and ($Name.Length -gt 0)) { $timers = @(foreach ($_name in $Name) { foreach ($timer in $timers) { if ($timer.Name -ine $_name) { continue } $timer } }) } # return return $timers } <# .SYNOPSIS Automatically loads timer ps1 files .DESCRIPTION Automatically loads timer ps1 files from either a /timers folder, or a custom folder. Saves space dot-sourcing them all one-by-one. .PARAMETER Path Optional Path to a folder containing ps1 files, can be relative or literal. .EXAMPLE Use-PodeTimers .EXAMPLE Use-PodeTimers -Path './my-timers' #> function Use-PodeTimers { [CmdletBinding()] param( [Parameter()] [string] $Path ) Use-PodeFolder -Path $Path -DefaultPath 'timers' } |