en-us/about_psf_taskengine.help.txt
TOPIC
about_psf_taskengine SHORT DESCRIPTION Explains the PSFramework's Task Engine component LONG DESCRIPTION #-------------------------------------------------------------------------# # Component Commands # #-------------------------------------------------------------------------# - Disable-PSFTaskEngineTask - Enable-PSFTaskEngineTask - Get-PSFTaskEngineCache - Get-PSFTaskEngineTask - Register-PSFTaskEngineTask - Set-PSFTaskEngineCache - Test-PSFTaskEngineCache - Test-PSFTaskEngineTask #-------------------------------------------------------------------------# # Table of Contents # #-------------------------------------------------------------------------# - Introduction - Running a task - Exchanging Information #-------------------------------------------------------------------------# # Introduction # #-------------------------------------------------------------------------# The Task Engine system of the PSFramework module is designed to enable module developers to offload slow code from their import process, as well as to schedule repeating maintenance tasks that run in the background. It also processes registered task sequentially, preventing spontaneous bursts of CPU loads due to too many tasks executing at once (as would be the case if each module provided its own solution). Finally, it is runspace-safe, enabling modules to schedule and manage tasks without having to worry about code duplication when that module is used in a runspace scenario. #-------------------------------------------------------------------------# # Running a task # #-------------------------------------------------------------------------# The prinmary command to use with the task engine is the function: Register-PSFTaskEngineTask In order to function, it needs a few pieces of information: - A unique name. Best prefix it with a module name (eg: 'mymodule.maintenance') - A Description This is optional, but helps with understanding what is happening in the background. A piece of self-documentation and highly recommended. - A scriptblock Because a task without something to do wouldn't be much of a task. - A schedule Either set it to run only once, or set it to run in a given interval. Example: Register-PSFTaskEngineTask -Name 'mymodule.buildcache' -ScriptBlock $ScriptBlock -Once -Description 'Builds the object cache used by the mymodule module' This will register the task to run the scriptblock stored in $ScriptBlock. It will only be run once at average priority. Example 2: Register-PSFTaskEngineTask -Name 'mymodule.maintenance' -ScriptBlock $ScriptBlock -Interval "00:05:00" -Delay "00:01:00" -Priority Critical -Description 'Performs critical system maintenance in order for the mymodule module to function' Registers the task contained in $ScriptBlock under the name 'mymodule.maintenance' - Sets it to execute every 5 minutes - Sets it to wait for 1 minute after registration before starting the first execution - Sets it to priority "Critical", ensuring it takes precedence over most other tasks. # The ScriptBlock # #-----------------# You can put pretty much anything you want to into the scriptblock that is registered to execute. You can access any module available on the computer, includuing the very module that registered the task! However no module is imported by default! Keep in mind, that not necessarily all users will place your module in one of the default paths, relying on implicit import may not work in that case! Both the main runspace and the task share the same configuration system however, so it is possible to share the modulepath by registering the modulebase in the configuration system. Note: The task should NOT use the configuration system to return information to the main runspace. See the next chapter on details, of how a task can offer information back to its parent. #-------------------------------------------------------------------------# # Exchanging Information # #-------------------------------------------------------------------------# Since the task is executed on another runspace - one you have no control over - you cannot easily share information across this boundary. In order to help with this issue, the PSFramework provides a cache that can be used to provide and update information by the task. The functions in the main runspace (what the user runs directly) can then access the information stored there. Example (Place this in your background task): Set-PSFTaskEngineCache -Module 'mymodule' -Name 'database-cache' -Value $results This will set the values retrieved as part of the task and stored in $results and store them under the modulename 'mymodule' and the cache name 'database-cache' (The names are arbitrary and not case sensitive). Example (Place this in your main function): $data = Get-PSFTaskEngineCache -Module 'mymodule' -Name 'database-cache' This will retrieve the values stored using the previous example. If the task hasn't run yet (or has failed), it will instead return $null. You can check, whether the task has run, by using the Test-PSFTaskEngineTask command. In cases where it is not certain, whether the task will store a result - or where the task may fail - you can also use Test-PSFTaskEngineCache, in order to test whether anything was written to the cache (note: It will return true, when 'anything' - including $null - was written to the cache by the task). #-------------------------------------------------------------------------# # Notes: # #-------------------------------------------------------------------------# Tasks can be temporarily disabled or enabled by running: - Disable-PSFTaskEngineTask - Enable-PSFTaskEngineTask Tasks are enabled by default The runspace executing tasks is a managed runspace and can be controlled using those functions (*-PSFRunspace). The task engine runspace will self-terminate when there will be no more tasks to execute, in order to conserve resources. Registering a task or enabling a task will enable the task engine runspace, if it is stopped at the time. KEYWORDS psframework taskengine |