DeviceLost.h File Reference

donner::gpu::DeviceLostState - the sticky device-loss condition of one backend root. More...

#include <atomic>
#include <chrono>
#include <cstdint>
#include <iosfwd>
#include <memory>
#include <mutex>
#include <vector>

Include dependency graph for DeviceLost.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::gpu::DeviceLossSnapshot
	Stable diagnostic view of the first declaration that won a device-loss condition. More...
class	donner::gpu::DeviceLossRelease
	Work a declared loss has to release: something blocked on the device behind a wait that only progress on the lost root would ever satisfy. More...
struct	donner::gpu::DeviceLostState
	Sticky device-loss condition of one backend root. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Enumerations
enum class	donner::gpu::DeviceLostWaitSite : std::uint8_t {   None ,   ReadbackMap ,   QueueIdle ,   Present }
	Which bounded wait gave up and declared the device lost. More...

Functions
std::ostream &	donner::gpu::operator<< (std::ostream &os, DeviceLostWaitSite site)
	Ostream output operator, e.g. QueueIdle.
bool	donner::gpu::DeclareDeviceLost (DeviceLostState &state)
	Declare state lost with no wait to attribute it to.
bool	donner::gpu::DeclareDeviceLostAfterWaitTimeout (DeviceLostState &state, DeviceLostWaitSite site, std::chrono::milliseconds elapsed)
	Declare state lost because a bounded wait at site gave up after elapsed.
DeviceLossSnapshot	donner::gpu::ReadDeviceLossSnapshot (const DeviceLostState &state)
	Reads the sticky loss and its first-winner attribution as one diagnostic snapshot.
void	donner::gpu::LogDeclaredDeviceLoss (const char *reason)
	Logs the cause of a device loss.

Detailed Description

donner::gpu::DeviceLostState - the sticky device-loss condition of one backend root.

A hung GPU driver can leave a fence or buffer-map wait blocked forever, in the worst case in uninterruptible kernel sleep. Donner cannot fix drivers, but no thread the application relies on may block unboundedly on the GPU: a hung device must surface as a detectable device-lost condition instead of a hung process. The condition belongs to the backend root rather than to any one runtime device, because several runtime devices routinely drive one root and a root that stopped answering has stopped answering all of them.

This header is deliberately free of the runtime's descriptors and handles (atomics, chrono, the standard containers and an ostream declaration only) so a wait loop can publish a loss without pulling the device in.

Enumeration Type Documentation

DeviceLostWaitSite

enum class donner::gpu::DeviceLostWaitSite : std::uint8_t

strong

Which bounded wait gave up and declared the device lost.

A hung device costs the full budget wherever it is first waited on, and the waits have very different budgets and callers, so "the device was declared lost" is not actionable on its own: a readback-map timeout points at buffer-map delivery, a queue-drain timeout points at submitted work never retiring. Recording which one gave up keeps that distinction in the diagnostics a failure report is assembled from.

Enumerator
None	No bounded wait has given up. A device lost with this site was reported by the backend's device-lost callback, not by a deadline.
ReadbackMap	A buffer-map wait for GPU-to-CPU readback (snapshot or surface capture).
QueueIdle	A wait for the GPU queue to drain (teardown, inter-submit serialization, submission completion).
Present	A present's wait for its frame's own work to finish before the frame is shown.

Function Documentation

DeclareDeviceLost()

bool donner::gpu::DeclareDeviceLost

(

DeviceLostState &

state

)

Declare state lost with no wait to attribute it to.

For losses the backend reports: there is no deadline behind them, so timedOutSite stays None and says exactly that. The call that declares the loss runs every release registered with DeviceLostState::addLossRelease before it returns.

Parameters

state

Shared device-lost record.

Returns

True when this call performed the false-to-true transition, so a caller can log the cause exactly once.

DeclareDeviceLostAfterWaitTimeout()

bool donner::gpu::DeclareDeviceLostAfterWaitTimeout	(	DeviceLostState &	state,
		DeviceLostWaitSite	site,
		std::chrono::milliseconds	elapsed )

Declare state lost because a bounded wait at site gave up after elapsed.

The attribution is written only when this call is the one that declares the loss. Two other writers reach the same flag and neither may claim the site: a later bounded wait, which gives up because the device is ALREADY hung (a consequence of the loss, never its cause), and the backend's device-lost callback, which has no wait to name. Deriving the claim from the flag's own transition covers both without a check-then-set window - reading the flag and then storing the site would let a driver-reported loss landing in between be relabelled as a wait timeout, which is the one misattribution an empty site exists to rule out.

Like DeclareDeviceLost, the declaring call runs every registered release before it returns, after the attribution is written, so whatever a release lets run sees the site.

Parameters

state	Shared device-lost record.
site	Which bounded wait gave up.
elapsed	Wall time that wait spent before giving up.

Returns

True when this call performed the false-to-true transition.

LogDeclaredDeviceLoss()

void donner::gpu::LogDeclaredDeviceLoss

(

const char *

reason

)

Logs the cause of a device loss.

Call it only from the caller that won the declaration, so the line appears exactly once per backend root no matter how many observers later read the condition.

Parameters

reason

Human-readable cause; null is logged as an absent reason rather than skipped, because the loss itself is the news.

operator<<()

std::ostream & donner::gpu::operator<<	(	std::ostream &	os,
		DeviceLostWaitSite	site )

Ostream output operator, e.g. QueueIdle.

Parameters

os	Output stream.
site	Value to output.