| Copyright | (C) 2026 Edward Kmett |
|---|---|
| License | UPL-1.0 AND BSD-3-Clause |
| Maintainer | Edward Kmett <ekmett@gmail.com> |
| Stability | experimental |
| Portability | GHC FFI; THC runtime services or native fallback implementation |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
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
- data Available a
- = Available a
- | Unsupported
- | Disabled
- | Denied
- | Unavailable
- data ThreadKind
- data ThreadInfo = ThreadInfo {}
- data ThreadAccounting = ThreadAccounting {}
- data CpuCoordinate = CpuCoordinate {
- cpuGroup :: Int
- cpuProcessor :: Int
- currentThreadInfo :: IO ThreadInfo
- currentThreadAccounting :: IO ThreadAccounting
- eligibleCPUs :: IO (Available [CpuCoordinate])
- data CpuAffinitySupport
- cpuAffinitySupport :: IO CpuAffinitySupport
- affinityApplied :: IO Bool
- forkOnWithAffinity :: Int -> (Bool -> IO ()) -> IO ThreadId
Documentation
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
| Functor Available # | |
| Eq a => Eq (Available a) # | |
| Ord a => Ord (Available a) # | |
Defined in THC.Runtime.Types | |
| Show a => Show (Available a) # | |
data ThreadKind Source #
Kind of thread observed by the service, not a handle to its host carrier.
Constructors
| NativeHaskellThread | |
| PlatformThread | |
| VirtualThread |
Instances
| Eq ThreadKind # | |
Defined in THC.Thread | |
| Ord ThreadKind # | |
Defined in THC.Thread Methods compare :: ThreadKind -> ThreadKind -> Ordering # (<) :: ThreadKind -> ThreadKind -> Bool # (<=) :: ThreadKind -> ThreadKind -> Bool # (>) :: ThreadKind -> ThreadKind -> Bool # (>=) :: ThreadKind -> ThreadKind -> Bool # max :: ThreadKind -> ThreadKind -> ThreadKind # min :: ThreadKind -> ThreadKind -> ThreadKind # | |
| Show ThreadKind # | |
Defined in THC.Thread Methods showsPrec :: Int -> ThreadKind -> ShowS # show :: ThreadKind -> String # showList :: [ThreadKind] -> ShowS # | |
data ThreadInfo Source #
Logical lock/request information is not evidence of OS pin acceptance.
Constructors
| ThreadInfo | |
Instances
| Eq ThreadInfo # | |
Defined in THC.Thread | |
| Show ThreadInfo # | |
Defined in THC.Thread Methods showsPrec :: Int -> ThreadInfo -> ShowS # show :: ThreadInfo -> String # showList :: [ThreadInfo] -> ShowS # | |
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.
Constructors
| ThreadAccounting | |
Instances
| Eq ThreadAccounting # | |
Defined in THC.Thread Methods (==) :: ThreadAccounting -> ThreadAccounting -> Bool # (/=) :: ThreadAccounting -> ThreadAccounting -> Bool # | |
| Show ThreadAccounting # | |
Defined in THC.Thread Methods showsPrec :: Int -> ThreadAccounting -> ShowS # show :: ThreadAccounting -> String # showList :: [ThreadAccounting] -> ShowS # | |
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
| |
Instances
| Eq CpuCoordinate # | |
Defined in THC.Thread Methods (==) :: CpuCoordinate -> CpuCoordinate -> Bool # (/=) :: CpuCoordinate -> CpuCoordinate -> Bool # | |
| Ord CpuCoordinate # | |
Defined in THC.Thread Methods compare :: CpuCoordinate -> CpuCoordinate -> Ordering # (<) :: CpuCoordinate -> CpuCoordinate -> Bool # (<=) :: CpuCoordinate -> CpuCoordinate -> Bool # (>) :: CpuCoordinate -> CpuCoordinate -> Bool # (>=) :: CpuCoordinate -> CpuCoordinate -> Bool # max :: CpuCoordinate -> CpuCoordinate -> CpuCoordinate # min :: CpuCoordinate -> CpuCoordinate -> CpuCoordinate # | |
| Show CpuCoordinate # | |
Defined in THC.Thread Methods showsPrec :: Int -> CpuCoordinate -> ShowS # show :: CpuCoordinate -> String # showList :: [CpuCoordinate] -> ShowS # | |
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.
data CpuAffinitySupport Source #
Strength of the runtime's affinity mechanism. Even pinned support does not prove that a particular thread's request was accepted.
Constructors
| NoCpuAffinity | |
| AdvisoryCpuAffinity | |
| PinnedCpuAffinity |
Instances
| Eq CpuAffinitySupport # | |
Defined in THC.Thread Methods (==) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # (/=) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # | |
| Ord CpuAffinitySupport # | |
Defined in THC.Thread Methods compare :: CpuAffinitySupport -> CpuAffinitySupport -> Ordering # (<) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # (<=) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # (>) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # (>=) :: CpuAffinitySupport -> CpuAffinitySupport -> Bool # max :: CpuAffinitySupport -> CpuAffinitySupport -> CpuAffinitySupport # min :: CpuAffinitySupport -> CpuAffinitySupport -> CpuAffinitySupport # | |
| Show CpuAffinitySupport # | |
Defined in THC.Thread Methods showsPrec :: Int -> CpuAffinitySupport -> ShowS # show :: CpuAffinitySupport -> String # showList :: [CpuAffinitySupport] -> ShowS # | |
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.