runtime_activity.go RawHistoryFolder

1package port
2
3import "context"
4
5// RuntimeActivitySnapshot is an engine-neutral view of outstanding native
6// runtime work that must settle before the process may idle out. Counts only:
7// generations and acknowledgement correlation live with the implementation.
8type RuntimeActivitySnapshot struct {
9	// PendingCreations counts accepted browser creations not yet resolved
10	// through OnAfterCreated or a definitive failure.
11	PendingCreations int
12	// ActiveViews counts registered live views, including views whose
13	// native close has started but whose GTK teardown is outstanding.
14	ActiveViews int
15	// PendingCleanup counts native-closed views whose queued GTK
16	// bridge/popup cleanup has not completed.
17	PendingCleanup int
18	// ActiveDownloads counts downloads with a terminal event outstanding.
19	ActiveDownloads int
20}
21
22// Quiescent reports whether no native work is outstanding.
23func (s RuntimeActivitySnapshot) Quiescent() bool {
24	return s.PendingCreations == 0 && s.ActiveViews == 0 && s.PendingCleanup == 0 && s.ActiveDownloads == 0
25}
26
27// RuntimeActivity is the application-port boundary for native runtime
28// quiescence. The initial snapshot and subscription are race-safe and
29// sequenced: Subscribe delivers the current snapshot synchronously, then all
30// later transitions in order. Unsubscribe at shutdown.
31type RuntimeActivity interface {
32	Snapshot() RuntimeActivitySnapshot
33	Subscribe(func(RuntimeActivitySnapshot)) (unsubscribe func())
34}
35
36// RuntimeActivityProvider is an optional Engine capability. Engines whose
37// native runtime has work that must settle before idle exit (CEF) implement
38// it; engines without such work (WebKit) do not, and callers treat that as
39// always quiescent.
40type RuntimeActivityProvider interface {
41	RuntimeActivity() RuntimeActivity
42}
43
44// EngineRuntimeActivity returns the engine's runtime activity, or nil when
45// the engine does not report any.
46func EngineRuntimeActivity(engine Engine) RuntimeActivity {
47	if provider, ok := engine.(RuntimeActivityProvider); ok && provider != nil {
48		return provider.RuntimeActivity()
49	}
50	return nil
51}
52
53// PersistenceDrain is the narrow activity/drain boundary for persistence
54// owners whose saves cross the GTK/database boundary. Active covers pending
55// debounce, in-flight capture/execution, and unsettled terminal failure.
56// WaitSettled blocks until settled or ctx ends; it must never be called on
57// the GTK thread when capture dispatches there.
58type PersistenceDrain interface {
59	Active() bool
60	WaitSettled(ctx context.Context) error
61}
62
63// AdmissionBoundary is the admission/work-lease contract shared by the relay
64// listener and the shutdown/residency policy. Infrastructure provides the
65// implementation; application code depends only on this boundary.
66type AdmissionBoundary interface {
67	// Acquire takes one work lease, reporting false when admission is
68	// closed. Callers send the existing error response instead of
69	// acknowledging.
70	Acquire() bool
71	// Release returns one work lease on dispatch settlement.
72	Release()
73	// Close atomically stops admission; in-flight leases drain.
74	Close()
75	// Reopen resumes admission after an invalidated seal.
76	Reopen()
77	// Closed reports whether admission is stopped.
78	Closed() bool
79	// Active reports the number of held leases.
80	Active() int
81	// OnDrained registers a callback for every transition to zero leases.
82	// Callbacks run without the gate lock and must not reenter it.
83	OnDrained(func())
84	// WaitDrained blocks until no leases are held or ctx ends, reporting
85	// false on expiry so shutdown never waits forever.
86	WaitDrained(ctx context.Context) bool
87}