Auto-generated from src/Core/Threading/. Do not edit by hand -- run build/Build-ModuleDocs.ps1 to regenerate.
- Get-ThreadCallStack
- Get-ThreadId
- Get-ThreadLastSeen
- Get-ThreadState
- Get-ThreadTree
- New-Thread
- New-ThreadPool
- Set-ThreadFrozen
- Set-ThreadProcessing
- Show-Threads
- Start-ThreadHouseKeeper
- Stop-Thread
- Test-ThreadRunning
- Write-ThreadTree
Public function
Synopsis: Initialize thread-local runtime state inside a new runspace.
Set-ThreadData is invoked inside threads created by New-Thread. It sets up
the base environment, configures the public and protected runtime containers,
registers the thread id, validates the requested command and finally invokes it
with the supplied parameters.
$PublicSpace
| Name | Type | Description | Default |
|---|---|---|---|
| PublicSpace | System.Object | Shared public runtime object to attach to the thread | $null |
$AccessControl
| Name | Type | Description | Default |
|---|---|---|---|
| AccessControl | System.Object | Access control descriptor to attach to protected runtime area | $null |
$ThreadId
| Name | Type | Description | Default |
|---|---|---|---|
| ThreadId | System.String | The thread id assigned by the creator | $null |
$Command
| Name | Type | Description | Default |
|---|---|---|---|
| Command | System.String | The command/function name to execute in the thread | $null |
$Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| Parameters | System.Hashtable | Named parameters to pass to Command |
@{} |
Varies. The invoked Command determines output; error conditions return structured cmdlet returns.
PS> Set-ThreadData -PublicSpace $GlobalPublic -AccessControl $ac -ThreadId $tid -Command 'RunWorker' -Parameters @{ 'Queue' = $q }Called exclusively by New-Thread; do not invoke directly. Calls New-ModuleBaseEnvironment to set up the runspace and sets (Get-GlobalRuntimeVariable).Protected.IsBackgroundDaemon to $true so that downstream functions know they are executing in a background context. Thread identity is tracked via Update-LoggingThreadLoggingId for log correlation.
Source: src/Core/Threading/Public/Set-ThreadData.ps1
Public function
Synopsis: Display the Icinga thread hierarchy.
Show-IcingaThreads is a small public wrapper that renders the current
thread hierarchy for the Icinga application by delegating to Show-Threads.
$AsObject
| Name | Type | Description | Default |
|---|---|---|---|
| AsObject | System.SwitchParameter | Return the tree as PSObjects instead of rendering | $false |
System.Array when -AsObject is set. Returns the root-level thread nodes
with a nested Children array representing the full hierarchy.
None otherwise. Writes a formatted thread tree to the logging system.
PS> Show-IcingaThreadsPS> $tree = Show-IcingaThreads -AsObject
PS> $tree | Select-Object Name, State, LastSeenThis wrapper calls Show-Threads and exists to provide a user-facing
command name for convenience.
Source: src/Core/Threading/Public/Show-IcingaThreads.ps1
Private function
Synopsis: Get a readable breadcrumb-style name for the current thread call stack.
Get-ThreadCallStack inspects the PowerShell call stack to construct a compact,
human-readable thread name by joining function names with '::'. It normalizes
scriptblock entries and removes internal Set-ThreadData frames.
System.String -- A single-line thread name derived from the call stack.
PS> Get-ThreadCallStackUsed for naming threads created with New-Thread to aid diagnostics and tracing.
Source: src/Core/Threading/Private/Get-ThreadCallStack.ps1
Private function
Synopsis: Return the current thread identifier used by our runtime.
Get-ThreadId returns the thread id stored in the runtime private threading
container. It is a convenience helper to avoid repeating the global variable path.
System.String -- The current thread GUID string, or $null if not set.
PS> Get-ThreadIdThe value is read from (Get-GlobalRuntimeVariable).Private.Threading.ThreadId.
Source: src/Core/Threading/Private/Get-ThreadId.ps1
Private function
Synopsis: Return seconds since the thread was last seen (heartbeat).
Get-ThreadLastSeen reads a thread's LastSeen timestamp from the global
thread registry and returns the elapsed seconds (rounded) since that timestamp.
If the thread or timestamp is missing, $null is returned.
$ThreadId
| Name | Type | Description | Default |
|---|---|---|---|
| ThreadId | System.String | The thread id to query. Defaults to current thread. | (Get-ThreadId) |
System.Double -- Seconds since the last heartbeat, or $null if the thread is unknown.
PS> Get-ThreadLastSeen -ThreadId $tidUsed by health checks and thread state transitions in the housekeeper.
Source: src/Core/Threading/Private/Get-ThreadLastSeen.ps1
Private function
Synopsis: Evaluate and normalize the runtime state of a thread.
Get-ThreadState inspects a thread's stored state and returns a normalized
status such as 'RUNNING', 'IDLE', 'BLOCKED', or the raw stored state when
unmodified. It uses the thread's LastSeen timestamp and KeepAlive flag to
differentiate between active and idle conditions.
$ThreadId
| Name | Type | Description | Default |
|---|---|---|---|
| ThreadId | System.String | The thread id to evaluate. Defaults to current thread. | (Get-ThreadId) |
System.String -- Normalisierter Thread-State (z.B. RUNNING, IDLE, BLOCKED).
PS> Get-ThreadState -ThreadId $tidRelies on configuration values such as (Get-GlobalRuntimeVariable).Public.Threading.IdleTime.
Source: src/Core/Threading/Private/Get-ThreadState.ps1
Private function
Synopsis: Build a hierarchical tree of all registered threads as PSObjects.
Get-ThreadTree collects every thread from the global thread registry and
assembles it into a list of root-level tree nodes. Each node holds the
resolved thread state, last-seen age, parameters and a Children array that
contains the child nodes in the same format -- forming a complete, self-contained
representation of the thread hierarchy without requiring further registry
lookups.
System.Array. Sorted array of root-level thread nodes. Each node is a PSObject with the following properties:
| Property | Type | Description |
|---|---|---|
| Id | System.String | Unique thread GUID |
| Name | System.String | Display name of the thread |
| Command | System.String | Entry-point command name |
| State | System.String | Resolved state (RUNNING, IDLE, ...) |
| LastSeen | System.Double | Seconds since last heartbeat |
| KeepAlive | System.Boolean | Whether the thread is kept alive |
| Parameters | System.Hashtable | Parameters passed to the command |
| ParentId | System.String | Parent thread GUID or $null |
| Children | System.Array | Ordered child nodes (same structure) |
PS> $tree = Get-ThreadTree
PS> $tree[0].ChildrenThe function resolves state and last-seen values at call time via
Get-ThreadState and Get-ThreadLastSeen.
Source: src/Core/Threading/Private/Get-ThreadTree.ps1
Private function
Synopsis: Create and (optionally) start a managed background PowerShell thread.
New-Thread creates a PowerShell runspace with a thread-local environment,
registers the thread in the global threading registry and optionally starts it.
The function supports keep-alive semantics and parent/child relationships.
$Command
| Name | Type | Description | Default |
|---|---|---|---|
| Command | System.String | The command (function) name to execute in the thread |
$Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| Parameters | System.Hashtable | Named parameters passed to the command | @{} |
$ParentThread
| Name | Type | Description | Default |
|---|---|---|---|
| ParentThread | System.String | Optional parent thread id (defaults to current thread) | $null |
$OverrideName
| Name | Type | Description | Default |
|---|---|---|---|
| OverrideName | System.String | Optional explicit display name for the created thread | $null |
$Start
| Name | Type | Description | Default |
|---|---|---|---|
| Start | System.SwitchParameter | When set, start the thread immediately after creation | $false |
$KeepAlive
| Name | Type | Description | Default |
|---|---|---|---|
| KeepAlive | System.SwitchParameter | When set, the housekeeper may restart the thread on failure | $false |
$WaitForJobs
| Name | Type | Description | Default |
|---|---|---|---|
| WaitForJobs | System.SwitchParameter | When set the thread is expected to wait for queued jobs | $false |
System.String. The newly created thread id.
PS> New-Thread -Command 'Start-Worker' -Parameters @{ 'Queue' = $q } -StartThis helper uses Set-ThreadData in the created runspace to initialize thread-local state.
Source: src/Core/Threading/Private/New-Thread.ps1
Private function
Synopsis: Create or return a shared PowerShell runspace pool for threads.
New-ThreadPool creates a RunspacePool with the given minimum and maximum
instances and caches it on the global runtime variable. If a pool already
exists, the cached instance is returned.
$MinInstances
| Name | Type | Description | Default |
|---|---|---|---|
| MinInstances | System.Int32 | Minimum number of runspaces in the pool | 1 |
$MaxInstances
| Name | Type | Description | Default |
|---|---|---|---|
| MaxInstances | System.Int32 | Maximum number of runspaces in the pool | (Get-GlobalRuntimeVariable).Public.Threading.MaxThreads |
System.Management.Automation.Runspaces.RunspacePool -- The newly created or cached runspace pool.
PS> New-ThreadPool -MinInstances 2 -MaxInstances 8The function currently uses the default InitialSessionState. Future work may enable JEA.
Source: src/Core/Threading/Private/New-ThreadPool.ps1
Private function
Synopsis: Mark a thread as FROZEN if it appears unresponsive.
Set-ThreadFrozen checks the last-seen timestamp for a given thread and, if
it exceeds the configured keep-alive threshold, sets the thread state to
FROZEN and emits a warning log entry.
$ThreadId
| Name | Type | Description | Default |
|---|---|---|---|
| ThreadId | System.String | The thread id to inspect. Defaults to current thread. | (Get-ThreadId) |
None -- Updates the thread state in the global registry and emits a warning log entry when frozen.
PS> Set-ThreadFrozen -ThreadId $tidThis helper is used by the housekeeper loop to detect and flag unresponsive threads.
Source: src/Core/Threading/Private/Set-ThreadFrozen.ps1
Private function
Synopsis: Mark the current thread as processing and refresh its heartbeat.
Set-ThreadProcessing updates the current thread's state to PROCESSING
and records the current timestamp in LastSeen to indicate activity.
None -- Modifies (Get-GlobalRuntimeVariable).Public.Threading.Threads for the current thread.
PS> Set-ThreadProcessingTypically called by worker loops when they start handling a job.
Source: src/Core/Threading/Private/Set-ThreadProcessing.ps1
Private function
Synopsis: Render or return the current thread hierarchy and status.
Show-Threads builds a complete thread tree via Get-ThreadTree and either
returns the structured tree objects or renders them as a formatted hierarchy
string and emits it to the logging system -- depending on the -AsObject
switch.
$AsObject
| Name | Type | Description | Default |
|---|---|---|---|
| AsObject | System.SwitchParameter | Return the tree as PSObjects instead of rendering | $false |
System.Array when -AsObject is set. Returns the root-level thread nodes
produced by Get-ThreadTree, each with a Children array for the full
hierarchy.
None otherwise. Writes a formatted thread hierarchy string to the logging queue.
PS> Show-ThreadsPS> $tree = Show-Threads -AsObject
PS> $tree[0].ChildrenRelies on Get-ThreadTree to build the hierarchy and Write-ThreadTree to
render individual branches.
Source: src/Core/Threading/Private/Show-Threads.ps1
Private function
Synopsis: Periodic housekeeper that monitors and manages thread lifecycle.
Start-ThreadHouseKeeper runs a loop that inspects all registered threads,
marks unresponsive threads as FROZEN, cleans up terminated or dead threads,
and attempts restarts for keep-alive threads. It sleeps between cycles to
reduce resource usage.
None -- Performs side-effect operations on the global thread registry and logs actions.
PS> Start-ThreadHouseKeeperThis function is intended to run as a background supervisory thread.
Source: src/Core/Threading/Private/Start-ThreadHouseKeeper.ps1
Private function
Synopsis: Request termination for a registered thread.
Stop-Thread marks a thread's state as TERMINATED in the global thread
registry. It validates the provided thread id and returns structured results
using Write-FunctionReturnValue when errors occur.
$ThreadId
| Name | Type | Description | Default |
|---|---|---|---|
| ThreadId | System.String | The id of the thread to stop | $null |
System.Management.Automation.PSCustomObject -- Strukturierter Rueckgabewert bei Fehler (via Write-FunctionReturnValue); None bei Erfolg.
PS> Stop-Thread -ThreadId $tidThe actual runspace shutdown and cleanup is handled by the housekeeper loop.
Source: src/Core/Threading/Private/Stop-Thread.ps1
Private function
Synopsis: Core loop gate to determine whether a thread should continue running.
Test-ThreadRunning is invoked by thread loops to decide if the thread
should continue executing. It updates heartbeats, refreshes logging ids,
checks the thread state and optionally validates TCP/WebSocket connectivity.
It also enforces lightweight sleeps to reduce CPU usage.
$CheckTcpConnection
| Name | Type | Description | Default |
|---|---|---|---|
| CheckTcpConnection | System.SwitchParameter | When set test the global TCP connection status | $false |
$CheckWebSocket
| Name | Type | Description | Default |
|---|---|---|---|
| CheckWebSocket | System.SwitchParameter | When set test the WebSocket connectivity | $false |
$NoSleep
| Name | Type | Description | Default |
|---|---|---|---|
| NoSleep | System.SwitchParameter | When set skip the default short sleep at loop start | $false |
System.Boolean -- $true when the thread should continue, $false otherwise.
while (Test-ThreadRunning) { Do-Work }This function performs multiple side effects (timestamp updates, logging id rotation) and is central to thread lifecycle management.
Source: src/Core/Threading/Private/Test-ThreadRunning.ps1
Private function
Synopsis: Append a formatted tree entry for a thread node to a StringBuilder.
Write-ThreadTree renders a single thread line (with name, id, state, age,
and parameters) into a supplied System.Text.StringBuilder and recursively
renders child nodes from the pre-built tree to produce the full hierarchical
view. The node is a PSObject as returned by Get-ThreadTree.
$Node
| Name | Type | Description | Default |
|---|---|---|---|
| Node | PSObject | Tree node as returned by Get-ThreadTree |
$null |
$StringBuilder
| Name | Type | Description | Default |
|---|---|---|---|
| StringBuilder | System.Text.StringBuilder | The builder to append lines to | $null |
$Level
| Name | Type | Description | Default |
|---|---|---|---|
| Level | System.Int32 | Nesting level for indentation | 0 |
None. Appends formatted lines to the provided StringBuilder instance.
$sb = [System.Text.StringBuilder]::new()
Get-ThreadTree | ForEach-Object { Write-ThreadTree -Node $_ -StringBuilder $sb }This function does not return a value; it operates by side-effects on the
supplied builder. Child nodes are read directly from $Node.Children -- no
additional registry lookups are performed.