-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell Library for Checking CPU Information
--   
--   Haskell Library for Checking CPU Information
@package cpuinfo
@version 0.1.0.1


-- | This module provides information about the processors available on a
--   system. Modern hardware provides not only multiple physical processors
--   and physical cores, but logical cores which may not have dedicated
--   execution resources. Intel's Hyper-Threading is an example of such a
--   technology, capable of providing two logical cores for every physical
--   core present on a supported physical processor.
--   
--   These additional logical cores increase the performance of some, but
--   not all workloads. Indeed, some parallel workloads may suffer a
--   performance decrease if all logical cores presented by the operating
--   system do not have dedicated physical resources. This is because
--   technologies providing supernumerary logical cores typically work by
--   scheduling multiple threads in a shared pool of execution resources,
--   e.g. ALUs and FPUs. If threads sharing a pool of execution resources
--   are doing the same sort of work there will be scheduling contention
--   for a single type of execution resource on the physical core.
--   
--   It is common for threaded Haskell programs to be run with <tt>+RTS
--   -N</tt>, causing the RTS to simply multiplex Haskell threads or sparks
--   over the number of logical cores available. However, if each logical
--   core does not have dedicated physical resources and the thread/spark
--   workloads are similar, then this might be slower than multiplexing
--   over fewer cores.
--   
--   This package allows a program to use information about the physical
--   and logical features of the available processors as a heuristic for
--   selecting the number of worker OS threads to use (e.g. via
--   <tt>setNumCapabilities</tt>). Some workloads may benefit from, for
--   example, using half the number of logical cores available if there are
--   in fact two logical cores for each physical core. This is typically
--   true of numerical workloads, but as always benchmarking should be
--   employed to evaluate the impact of different heuristics.
--   
--   In its current state this module can only collect information from
--   Linux systems with a kernel from the 2.6 branch or later by reading
--   <tt>/proc/cpuinfo</tt>. If this module is unable to provide
--   information on your system please file a bug including your
--   <tt>/proc/cpuinfo</tt>. Help providing Windows support would be
--   greatly appreciated!
module System.CPU

-- | Representation of a logical processor and its features.
data CPU
CPU :: !Word32 -> !(Maybe ByteString) -> !(Maybe Word32) -> !(Maybe ByteString) -> !(Maybe Word32) -> !(Maybe Word32) -> !Double -> !(Maybe Word32) -> !Word32 -> !Word32 -> !Word32 -> !(Maybe Word32) -> !(Maybe Bool) -> !(Maybe Bool) -> !(Maybe [ByteString]) -> !Double -> !(Maybe Word32) -> !(Maybe Word32) -> !(Maybe Word32) -> CPU

-- | Logical Processor Index
[processorID] :: CPU -> !Word32

-- | CPU Vendor
[vendor] :: CPU -> !(Maybe ByteString)

-- | CPU Model Number
[model] :: CPU -> !(Maybe Word32)

-- | CPU Model Name
[modelName] :: CPU -> !(Maybe ByteString)

-- | CPU Model Revision
[revision] :: CPU -> !(Maybe Word32)

-- | CPU Microcode Revision
[microcode] :: CPU -> !(Maybe Word32)

-- | Processor Frequency
[freq] :: CPU -> !Double

-- | CPU Cache Size. (TODO figure out how to get the cache topology)
[cache] :: CPU -> !(Maybe Word32)

-- | Physical Processor Index
[physicalID] :: CPU -> !Word32

-- | Number of Physical Cores on this Physical Processor.
[siblings] :: CPU -> !Word32

-- | Physical Core Index
[coreID] :: CPU -> !Word32

-- | CPU APIC Index
[apicID] :: CPU -> !(Maybe Word32)

-- | Whether or not the Physical Core provides a floating point unit.
[fpu] :: CPU -> !(Maybe Bool)

-- | Whether or not the Physical Core provides a floating point exception
--   unit.
[fpuExcept] :: CPU -> !(Maybe Bool)

-- | Vendor-specific CPU flags.
[flags] :: CPU -> !(Maybe [ByteString])

-- | MIPS approximation computed by the Linux kernel on boot.
[bogoMIPS] :: CPU -> !Double

-- | Cache line size in bytes.
[cacheAlignment] :: CPU -> !(Maybe Word32)

-- | Physical address width.
[physicalAddress] :: CPU -> !(Maybe Word32)

-- | Virtual address width.
[virtualAddress] :: CPU -> !(Maybe Word32)

-- | Read <tt>/proc/cpuinfo</tt> and try to parse the output. If this
--   function throws an error on your system, please file a bug report with
--   your <tt>/proc/cpuinfo</tt> contents and CPU specifications.
getCPUs :: IO [CPU]

-- | Read <tt>/proc/cpuinfo</tt> and try to parse the output. If this
--   function returns <a>Nothing</a> on your system, please file a bug
--   report with your <tt>/proc/cpuinfo</tt> contents and CPU
--   specifications.
tryGetCPUs :: IO (Maybe [CPU])

-- | Counts the number of physical processors in the system. A physical
--   processor corresponds to a single CPU unit in a single socket, i.e.
--   unless you have a multi-socket motherboard, this number will be one.
physicalProcessors :: [CPU] -> Int

-- | Counts the number of physical cores in the system. A physical core is
--   an independent processing unit that reads and executes instructions on
--   its own, but potentially shares its die (and other resources) with
--   other cores.
physicalCores :: [CPU] -> Int

-- | Counts the number of logical cores in the system. A logical core is a
--   virtual processing unit exposed to the operating system, that may or
--   may not directly correspond with an independent physical processing
--   unit, e.g. a hyperthread appears as an independent processing unit to
--   the operating system, but has no physically dedicated execution
--   resources.
logicalCores :: [CPU] -> Int

-- | The hyperthreading factor is the number of logical cores divided by
--   the number of physical cores. This quantity indicates the degree to
--   which physical execution resources are shared among logical
--   processors, and may be used to tune parallel applications.
hyperthreadingFactor :: [CPU] -> Rational

-- | If hyperthreading is in use, the <a>hyperthreadingFactor</a> will be
--   greater than 1.
hyperthreadingInUse :: [CPU] -> Bool
instance Control.DeepSeq.NFData System.CPU.CPU
instance GHC.Generics.Generic System.CPU.CPU
instance Data.Data.Data System.CPU.CPU
instance GHC.Show.Show System.CPU.CPU
instance GHC.Read.Read System.CPU.CPU
instance GHC.Classes.Ord System.CPU.CPU
instance GHC.Classes.Eq System.CPU.CPU
