pulp::platform Namespace Reference

Device capability vocabulary: one tier ladder, one thermal ladder, and the projection from observed inputs onto them. More...

Namespaces
namespace	detail
namespace	win

Classes
struct	ProcessResult
	Result of a completed child process. More...
struct	ProcessOptions
	Options for child process execution. More...
class	ChildProcessInputChannel
	Move-only parent endpoint of the child's inherited standard-input channel. More...
class	ChildProcess
	Cross-platform child process with timeout, cancellation, and line-by-line output callbacks. More...
class	Clipboard
class	DBus
struct	DeviceCapabilityInputs
	What a shell observed about the device it is running on. More...
struct	SafeAreaInsets
	Safe-area insets in CSS-pixel space (already divided by content_scale). More...
struct	KeyboardInset
	Soft-keyboard inset (mobile only). More...
struct	DisplayInfo
	Logical display geometry. More...
struct	EnvironmentChange
	Bitmask of fields that changed in the snapshot delivered to a listener. More...
struct	EnvironmentState
	Snapshot of the full environment state. More...
class	Environment
	In-process notifier. More...
struct	FileFilter
class	FileDialog
class	PermissionsOverride
	Test helper: scope-guarded override. More...
class	PopupMenu
struct	ProgressEvent
	A structured progress event parsed from a PROGRESS:TYPE:PAYLOAD line. More...
class	ProgressParser
	Parses lines matching the PROGRESS:TYPE:PAYLOAD protocol and fires a callback for each match. More...
struct	SpecialDirInputs
	Everything the resolver may read, so every platform's layout can be computed (and tested) on any host. More...

Typedefs
using	StandardInputByteProvider
	Produces private standard-input bytes after the child has been spawned.
using	StandardInputChannelSession
	Owns a post-spawn exchange over the child's private inherited input channel.
using	NativeWindowHandle = void*
using	NativeViewHandle = void*
using	NativeDisplayHandle = void*
using	RequestCallback = std::function<void(PermissionState)>

Enumerations
enum class	OS {   macOS , iOS , Windows , Linux ,   Android , Unknown }
enum class	Arch {   x86_64 , ARM64 , ARM32 , x86 ,   Unknown }
enum class	Compiler {   Clang , GCC , MSVC , AppleClang ,   Unknown }
enum class	Endian { Little , Big }
enum class	DeviceCapabilityTier : std::uint8_t { Constrained = 0 , Standard = 1 , Full = 2 }
	How much of the product a device can carry, on one ascending ladder. More...
enum class	ThermalState : std::uint8_t { Nominal = 0 , Fair = 1 , Serious = 2 , Critical = 3 }
	Live thermal pressure, ascending in heat. More...
enum class	PointerPrecision : std::uint8_t { Coarse = 0 , Fine = 1 }
	Precision of the device's primary pointing device. More...
enum class	ColorScheme : uint8_t { light , dark , unknown }
	Light/dark color scheme reported by the OS. More...
enum class	LifecycleState : uint8_t { foreground , inactive , background , unknown }
	Coarse foreground/background lifecycle state. More...
enum class	Orientation : uint8_t {   portrait , portrait_upside_down , landscape_left , landscape_right ,   flat , unknown }
	Device orientation. More...
enum class	MemoryPressure : uint8_t { normal , moderate , critical }
	Memory pressure level. More...
enum class	Permission {   Microphone , Camera , BluetoothMidi , LocalNetwork ,   Notifications , BackgroundAudio , ForegroundService }
enum class	PermissionState { NotDetermined , Granted , Denied , Restricted }
enum class	RevealOutcome {   revealed , opened_containing_folder , not_found , unsupported ,   failed }
	What reveal_in_file_manager managed to do. More...
enum class	SpecialDir {   home , documents , desktop , music ,   app_data , app_data_shared , config , temp ,   cache , logs , current_executable , bundle_dir ,   user_presets }
enum class	SpecialDirOs {   macos , ios , windows , linux_desktop ,   android , web }
	Operating system a path is shaped for. More...

Functions
ProcessResult	exec (const std::string &command, const std::vector< std::string > &args={}, int timeout_ms=30000)
	Convenience: run a command and capture output (blocking).
std::optional< std::filesystem::path >	find_on_path (const std::string &binary_name)
	Check if a binary exists on PATH. Returns the full path if found.
std::string	file_uri_to_path (const std::string &uri)
	Convert a file:// URI to a local filesystem path (percent-decoded).
constexpr DeviceCapabilityTier	project_device_capability_tier (DeviceCapabilityInputs inputs)
	Projects observed capabilities onto the tier ladder.
void	start_environment_observer_mac ()
void	start_environment_observer ()
PermissionState	query (Permission p)
	Current state. Never blocks, never shows UI.
void	request (Permission p, RequestCallback cb)
	Async request.
bool	has_platform_backend ()
	True when a real platform backend is wired (iOS / Android).
const char *	to_string (RevealOutcome outcome) noexcept
	Short stable name for an outcome ("revealed", "not_found", ...).
RevealOutcome	reveal_in_file_manager (const std::filesystem::path &path)
	Show path in the platform file manager: Finder (NSWorkspace activateFileViewerSelectingURLs), Windows Explorer (SHOpenFolderAndSelectItems), or on Linux the containing folder via xdg-open.
std::string_view	special_dir_name (SpecialDir kind) noexcept
	Stable lower_snake_case name, for diagnostics and tests.
std::filesystem::path	special_dir (SpecialDir kind)
	Resolve kind for the running process. Empty when unavailable.
void	set_special_dir_override (SpecialDir kind, std::filesystem::path path)
	Replace the resolved location for kind (a mobile host that learns its sandbox paths late, a test that must not touch the real home).
void	clear_special_dir_overrides ()
SpecialDirOs	host_special_dir_os () noexcept
	The host OS this binary was built for.
std::string	special_dir_for (SpecialDirOs os, SpecialDir kind, const SpecialDirInputs &inputs)
	Resolve kind for os from inputs alone. Empty string when unavailable.

Variables
constexpr OS	current_os = OS::macOS
constexpr bool	is_apple = true
constexpr bool	is_macos = (current_os == OS::macOS)
constexpr bool	is_ios = (current_os == OS::iOS)
constexpr bool	is_windows = (current_os == OS::Windows)
constexpr bool	is_linux = (current_os == OS::Linux)
constexpr bool	is_android = (current_os == OS::Android)
constexpr bool	is_desktop = is_macos || is_windows || is_linux
constexpr bool	is_mobile = is_ios || is_android
constexpr Arch	current_arch = Arch::Unknown
constexpr bool	is_arm = (current_arch == Arch::ARM64 || current_arch == Arch::ARM32)
constexpr bool	is_x86 = (current_arch == Arch::x86_64 || current_arch == Arch::x86)
constexpr bool	is_64bit = (current_arch == Arch::x86_64 || current_arch == Arch::ARM64)
constexpr Compiler	current_compiler = Compiler::Unknown
constexpr Endian	current_endian = Endian::Little
constexpr bool	is_little_endian = (current_endian == Endian::Little)
constexpr bool	is_big_endian = (current_endian == Endian::Big)
constexpr bool	is_debug = true
constexpr std::size_t	kDeviceCapabilityTierCount = 3
constexpr std::size_t	kThermalStateCount = 4
constexpr std::uint64_t	kStandardTierMemoryBytes = 3ull * 1024 * 1024 * 1024
	Memory floor for DeviceCapabilityTier::Standard.
constexpr std::uint64_t	kFullTierMemoryBytes = 8ull * 1024 * 1024 * 1024
	Memory floor for DeviceCapabilityTier::Full.
constexpr std::uint32_t	kStandardTierCoreCount = 4
	Core-count floor for DeviceCapabilityTier::Standard.
constexpr std::uint32_t	kFullTierCoreCount = 8
	Core-count floor for DeviceCapabilityTier::Full.
constexpr std::array< SpecialDir, 13 >	kAllSpecialDirs

Detailed Description

Device capability vocabulary: one tier ladder, one thermal ladder, and the projection from observed inputs onto them.

Everything here is an observation about the machine or a pure function of observations. What the product then grants at a given rung is policy, and policy is not here: pulp/format/device_quotas.hpp holds the quota table, at a rung the engine modules cannot reach. core/platform is named in every row of the engine's declared dependency floors, so anything placed here is reachable by every module and no floor row can object to it — which makes it the right address for a shared vocabulary and the wrong address for a budget.

This header is deliberately dependency-free. It includes no Pulp header, so it cannot name a document, a session, a transport, or a view, and every entry point is a constexpr free function over by-value trivially-copyable inputs. A projection that cannot reach mutable state by construction needs no runtime guard against mutating one.

Typedef Documentation

NativeDisplayHandle

using pulp::platform::NativeDisplayHandle = void*

NativeViewHandle

using pulp::platform::NativeViewHandle = void*

NativeWindowHandle

using pulp::platform::NativeWindowHandle = void*

RequestCallback

using pulp::platform::RequestCallback = std::function<void(PermissionState)>

StandardInputByteProvider

using pulp::platform::StandardInputByteProvider

Initial value:

 
    std::function<std::optional<std::vector<std::uint8_t>>(int child_process_id)>

Produces private standard-input bytes after the child has been spawned.

Returning std::nullopt rejects the launch. The callback runs synchronously outside ChildProcess's internal lock, may call non-mutating observers, and must not block indefinitely: it is caller code and cannot be preempted. Time spent in the callback consumes the standard-input delivery deadline.

StandardInputChannelSession

using pulp::platform::StandardInputChannelSession

Initial value:

 
    std::function<bool(int child_process_id, ChildProcessInputChannel channel,
                       std::chrono::steady_clock::time_point deadline)>

Owns a post-spawn exchange over the child's private inherited input channel.

The callback runs synchronously outside ChildProcess's internal lock and must bound every blocking operation to the supplied deadline. Like the byte provider above, it is caller code and cannot safely be preempted.

Enumeration Type Documentation

Arch

enum class pulp::platform::Arch

strong

Enumerator
x86_64
ARM64
ARM32
x86
Unknown

ColorScheme

enum class pulp::platform::ColorScheme : uint8_t

strong

Light/dark color scheme reported by the OS.

Enumerator
light
dark
unknown	Platform did not report; treat as dark per Pulp's default theme.

Compiler

enum class pulp::platform::Compiler

strong

Enumerator
Clang
GCC
MSVC
AppleClang
Unknown

DeviceCapabilityTier

enum class pulp::platform::DeviceCapabilityTier : std::uint8_t

strong

How much of the product a device can carry, on one ascending ladder.

There is exactly one ladder. The browser lane's Tier A/B/C and the mobile lane's M-A/M-B/M-C are the same three rungs named twice, so they are the same three enumerators here:

Rung	Browser	Mobile	Shape
Constrained	Tier A	M-A	Review and perform; no local realtime
Standard	Tier B	M-B	Authoring-complete
Full	Tier C	M-C	Precision authoring with headroom

The rung is computed from observable inputs (see DeviceCapabilityInputs), never assumed from form factor: a tablet with a keyboard and a phone-sized browser tab land wherever their capabilities put them.

Enumerator
Constrained
Standard
Full

Endian

enum class pulp::platform::Endian

strong

Enumerator
Little
Big

LifecycleState

enum class pulp::platform::LifecycleState : uint8_t

strong

Coarse foreground/background lifecycle state.

Mobile platforms drive this from the activity/scene lifecycle; desktop drives from the active-window observer (NSApp resignActive on macOS, WM_ACTIVATEAPP on Windows, _NET_ACTIVE_WINDOW on X11).

Enumerator
foreground
inactive	App is visible but not the focused window (split-screen, banner).
background
unknown

MemoryPressure

enum class pulp::platform::MemoryPressure : uint8_t

strong

Memory pressure level.

Mirrors Android's TRIM_MEMORY tiers + iOS's didReceiveMemoryWarning (which becomes critical). Desktop platforms emit normal only — they don't have a kernel-driven LMK.

Enumerator
normal
moderate	Some background processes were killed; trim soft caches.
critical	Foreground app is the next likely target; release optional state.

Orientation

enum class pulp::platform::Orientation : uint8_t

strong

Device orientation.

flat is "screen facing up" — used by mobile to disable orientation-driven layout when the device is lying on a table.

Enumerator
portrait
portrait_upside_down
landscape_left
landscape_right
flat
unknown

OS

enum class pulp::platform::OS

strong

Enumerator
macOS
iOS
Windows
Linux
Android
Unknown

Permission

enum class pulp::platform::Permission

strong

Enumerator
Microphone
Camera
BluetoothMidi
LocalNetwork
Notifications
BackgroundAudio
ForegroundService

PermissionState

enum class pulp::platform::PermissionState

strong

Enumerator
NotDetermined
Granted
Denied
Restricted

PointerPrecision

enum class pulp::platform::PointerPrecision : std::uint8_t

strong

Precision of the device's primary pointing device.

Enumerator
Coarse	Touch or another pointer whose contact area exceeds a small target.
Fine	Mouse, trackpad, or stylus with sub-target precision.

RevealOutcome

enum class pulp::platform::RevealOutcome

strong

What reveal_in_file_manager managed to do.

The outcome is reported honestly per platform rather than collapsed to a bool, because the platforms do not offer the same capability.

Enumerator
revealed	The platform file manager was asked to show the item selected in its parent folder (macOS Finder, Windows Explorer).
opened_containing_folder	The item's containing folder was opened but the item itself could not be selected (Linux: no portable "select this file" request exists).
not_found	The path does not exist; nothing was shown.
unsupported	This platform has no file manager to ask (iOS, Android, or a Linux system without xdg-open).
failed	The platform call was attempted and failed.

SpecialDir

enum class pulp::platform::SpecialDir

strong

Enumerator
home
documents
desktop
music
app_data	Per-user application data.
app_data_shared	Application data shared by every user of the machine.
config	Per-user settings root (an XDG distinction; equals app_data off Linux).
temp
cache
logs
current_executable
bundle_dir
user_presets

SpecialDirOs

enum class pulp::platform::SpecialDirOs

strong

Operating system a path is shaped for.

Distinct from platform::OS because WebAssembly has its own layout.

Enumerator
macos
ios
windows
linux_desktop
android
web

ThermalState

enum class pulp::platform::ThermalState : std::uint8_t

strong

Live thermal pressure, ascending in heat.

Four rungs, chosen to be the coarsest ladder every reporting platform can be projected onto without inventing precision it does not have. Platforms with a finer ladder collapse into these; a platform with no thermal API at all can only ever report Nominal, which is why the absence of a thermal API lowers the capability tier rather than being ignored — see DeviceCapabilityInputs::thermal_reporting_available.

Consumers index a quota table by tier and thermal state together; the table belongs to the consumer, not to the platform layer.

Enumerator
Nominal
Fair
Serious
Critical

Function Documentation

clear_special_dir_overrides()

void pulp::platform::clear_special_dir_overrides

(

)

exec()

ProcessResult pulp::platform::exec	(	const std::string &	command,
		const std::vector< std::string > &	args = {},
		int	timeout_ms = 30000 )

Convenience: run a command and capture output (blocking).

file_uri_to_path()

std::string pulp::platform::file_uri_to_path

(

const std::string &

uri

)

Convert a file:// URI to a local filesystem path (percent-decoded).

Returns the input unchanged if it has no file:// scheme. Pure + testable everywhere.

find_on_path()

std::optional< std::filesystem::path > pulp::platform::find_on_path

(

const std::string &

binary_name

)

Check if a binary exists on PATH. Returns the full path if found.

has_platform_backend()

bool pulp::platform::has_platform_backend

(

)

True when a real platform backend is wired (iOS / Android).

False when the desktop / unsupported backend is active — useful for diagnostics and feature gating.

host_special_dir_os()

SpecialDirOs pulp::platform::host_special_dir_os ( )

noexcept

The host OS this binary was built for.

project_device_capability_tier()

DeviceCapabilityTier pulp::platform::project_device_capability_tier ( DeviceCapabilityInputs inputs )

nodiscardconstexpr

Projects observed capabilities onto the tier ladder.

Each axis independently states the highest rung it can support, and the result is the lowest of those: capability is a weakest-link property, so a device with sixteen cores and half a gigabyte is not a Full-tier device. Structuring it this way keeps each axis's contribution separately reviewable instead of hiding it in a cascade of conditions.

query()

PermissionState pulp::platform::query

(

Permission

p

)

Current state. Never blocks, never shows UI.

request()

void pulp::platform::request	(	Permission	p,
		RequestCallback	cb )

Async request.

cb is invoked exactly once with the resolved state. On backends with no UI gate, the callback fires synchronously with the same value query() would return.

reveal_in_file_manager()

RevealOutcome pulp::platform::reveal_in_file_manager

(

const std::filesystem::path &

path

)

Show path in the platform file manager: Finder (NSWorkspace activateFileViewerSelectingURLs), Windows Explorer (SHOpenFolderAndSelectItems), or on Linux the containing folder via xdg-open.

A directory is selected within its parent on macOS and Windows. Checks existence first, so a missing path yields not_found without touching the shell. Call from the main/UI thread.

set_special_dir_override()

void pulp::platform::set_special_dir_override	(	SpecialDir	kind,
		std::filesystem::path	path )

Replace the resolved location for kind (a mobile host that learns its sandbox paths late, a test that must not touch the real home).

An empty path removes the override. Thread-safe.

special_dir()

std::filesystem::path pulp::platform::special_dir

(

SpecialDir

kind

)

Resolve kind for the running process. Empty when unavailable.

special_dir_for()

std::string pulp::platform::special_dir_for	(	SpecialDirOs	os,
		SpecialDir	kind,
		const SpecialDirInputs &	inputs )

Resolve kind for os from inputs alone. Empty string when unavailable.

special_dir_name()

std::string_view pulp::platform::special_dir_name ( SpecialDir kind )

noexcept

Stable lower_snake_case name, for diagnostics and tests.

start_environment_observer()

void pulp::platform::start_environment_observer ( )

inline

start_environment_observer_mac()

void pulp::platform::start_environment_observer_mac

(

)

to_string()

const char * pulp::platform::to_string ( RevealOutcome outcome )

noexcept

Short stable name for an outcome ("revealed", "not_found", ...).

Variable Documentation

current_arch

Arch pulp::platform::current_arch = Arch::Unknown

inlineconstexpr

current_compiler

Compiler pulp::platform::current_compiler = Compiler::Unknown

inlineconstexpr

current_endian

Endian pulp::platform::current_endian = Endian::Little

inlineconstexpr

current_os

OS pulp::platform::current_os = OS::macOS

inlineconstexpr

is_64bit

bool pulp::platform::is_64bit = (current_arch == Arch::x86_64 || current_arch == Arch::ARM64)

inlineconstexpr

is_android

bool pulp::platform::is_android = (current_os == OS::Android)

inlineconstexpr

is_apple

bool pulp::platform::is_apple = true

inlineconstexpr

is_arm

bool pulp::platform::is_arm = (current_arch == Arch::ARM64 || current_arch == Arch::ARM32)

inlineconstexpr

is_big_endian

bool pulp::platform::is_big_endian = (current_endian == Endian::Big)

inlineconstexpr

is_debug

bool pulp::platform::is_debug = true

inlineconstexpr

is_desktop

bool pulp::platform::is_desktop = is_macos || is_windows || is_linux

inlineconstexpr

is_ios

bool pulp::platform::is_ios = (current_os == OS::iOS)

inlineconstexpr

is_linux

bool pulp::platform::is_linux = (current_os == OS::Linux)

inlineconstexpr

is_little_endian

bool pulp::platform::is_little_endian = (current_endian == Endian::Little)

inlineconstexpr

is_macos

bool pulp::platform::is_macos = (current_os == OS::macOS)

inlineconstexpr

is_mobile

bool pulp::platform::is_mobile = is_ios || is_android

inlineconstexpr

is_windows

bool pulp::platform::is_windows = (current_os == OS::Windows)

inlineconstexpr

is_x86

bool pulp::platform::is_x86 = (current_arch == Arch::x86_64 || current_arch == Arch::x86)

inlineconstexpr

kAllSpecialDirs

std::array<SpecialDir, 13> pulp::platform::kAllSpecialDirs

inlineconstexpr

Initial value:

= {
    SpecialDir::home,
    SpecialDir::documents,
    SpecialDir::desktop,
    SpecialDir::music,
    SpecialDir::app_data,
    SpecialDir::app_data_shared,
    SpecialDir::config,
    SpecialDir::temp,
    SpecialDir::cache,
    SpecialDir::logs,
    SpecialDir::current_executable,
    SpecialDir::bundle_dir,
    SpecialDir::user_presets,
}

kDeviceCapabilityTierCount

std::size_t pulp::platform::kDeviceCapabilityTierCount = 3

inlineconstexpr

kFullTierCoreCount

std::uint32_t pulp::platform::kFullTierCoreCount = 8

inlineconstexpr

Core-count floor for DeviceCapabilityTier::Full.

kFullTierMemoryBytes

std::uint64_t pulp::platform::kFullTierMemoryBytes = 8ull * 1024 * 1024 * 1024

inlineconstexpr

Memory floor for DeviceCapabilityTier::Full.

kStandardTierCoreCount

std::uint32_t pulp::platform::kStandardTierCoreCount = 4

inlineconstexpr

Core-count floor for DeviceCapabilityTier::Standard.

kStandardTierMemoryBytes

std::uint64_t pulp::platform::kStandardTierMemoryBytes = 3ull * 1024 * 1024 * 1024

inlineconstexpr

Memory floor for DeviceCapabilityTier::Standard.

kThermalStateCount

std::size_t pulp::platform::kThermalStateCount = 4

inlineconstexpr