thc:runtime
Copyright(C) 2026 Edward Kmett
LicenseUPL-1.0 AND BSD-3-Clause
MaintainerEdward Kmett <ekmett@gmail.com>
Stabilityexperimental
PortabilityGHC FFI; THC runtime services or native fallback implementation
Safe HaskellTrustworthy
LanguageHaskell2010

THC.Thread

Description

Current-thread observations. No API exposes a carrier handle, arbitrary host-thread access, raw pinning or Java interruption. Guest forks currently use platform threads; affinity operations refuse virtual-thread callers.

Synopsis

Documentation

data Available a Source #

An absent metric is not zero. Queries never enable JVM-wide monitoring. fmap transforms a genuine value and preserves every non-value status:

>>> fmap (+ 1) (Available (41 :: Int))
Available 42
>>> fmap (+ 1) (Disabled :: Available Int)
Disabled
>>> map (fmap (+ 1)) [Unsupported, Disabled, Denied, Unavailable :: Available Int]
[Unsupported,Disabled,Denied,Unavailable]

Constructors

Available a

A genuine value; its scope is specified by the query.

Unsupported

The runtime or provider does not implement this service.

Disabled

Supported, but its instrumentation or sink is switched off.

Denied

The current context or host security policy forbids access.

Unavailable

Normally supported, but no value is currently available.

Instances

Instances details
Functor Available # 
Instance details

Defined in THC.Runtime.Types

Methods

fmap :: (a -> b) -> Available a -> Available b #

(<$) :: a -> Available b -> Available a #

Eq a => Eq (Available a) # 
Instance details

Defined in THC.Runtime.Types

Methods

(==) :: Available a -> Available a -> Bool #

(/=) :: Available a -> Available a -> Bool #

Ord a => Ord (Available a) # 
Instance details

Defined in THC.Runtime.Types

Show a => Show (Available a) # 
Instance details

Defined in THC.Runtime.Types

data ThreadKind Source #

Kind of thread observed by the service, not a handle to its host carrier.

Instances

Instances details
Eq ThreadKind # 
Instance details

Defined in THC.Thread

Ord ThreadKind # 
Instance details

Defined in THC.Thread

Show ThreadKind # 
Instance details

Defined in THC.Thread

data ThreadInfo Source #

Logical lock/request information is not evidence of OS pin acceptance.

Instances

Instances details
Eq ThreadInfo # 
Instance details

Defined in THC.Thread

Show ThreadInfo # 
Instance details

Defined in THC.Thread

data ThreadAccounting Source #

Cumulative accounting for the currently executing JVM thread. Does not enable monitoring, and is not an allocation/time budget. On a platform thread these counters include other host work performed on that thread.

Instances

Instances details
Eq ThreadAccounting # 
Instance details

Defined in THC.Thread

Show ThreadAccounting # 
Instance details

Defined in THC.Thread

data CpuCoordinate Source #

OS coordinate: Linux group zero plus sparse OS CPU ID; Windows processor group plus processor number. These are not GHC capability IDs.

Constructors

CpuCoordinate 

Fields

currentThreadInfo :: IO ThreadInfo Source #

Inspect the caller's thread and logical capability without changing its scheduling or affinity. Fields are independently sampled.

currentThreadAccounting :: IO ThreadAccounting Source #

Sample the executing JVM thread's cumulative counters. This neither enables monitoring nor isolates this guest's work from other carrier work.

eligibleCPUs :: IO (Available [CpuCoordinate]) Source #

Initial context eligibility in dense capability order, capped by the JVM's CPU capacity. This is not a live process-affinity query. Unavailable discovery is explicit, rather than a fabricated list of CPU IDs.

cpuAffinitySupport :: IO CpuAffinitySupport Source #

Compatibility query preserving the original API. Native GHC returns NoCpuAffinity: ordinary GHC forkOn promises a capability, not a physical CPU. This does not inspect +RTS -qa. For detailed failure status, inspect threadAffinitySupport in currentThreadInfo.

affinityApplied :: IO Bool Source #

Did this registered THC fork's initial native request succeed? False also covers unavailable support or no request. Acceptance is not a bound-thread TLS guarantee, nor a promise against subsequent OS policy changes.

forkOnWithAffinity :: Int -> (Bool -> IO ()) -> IO ThreadId Source #

Like forkOn, with the child's initial native-affinity acceptance. The callback always runs, including unavailable/rejected affinity. Preserves lazy action evaluation and inherited masking. The integer is a capability index, not an OS CPU ID; advisory acceptance remains advisory.