solid_objects 0.12.1 → 0.13.1

data/docs/dashboard.md

@@ -0,0 +1,200 @@
+# Operator dashboard
+
+`SolidObjects::Web` is a Rack application that shows what the actor runtime is
+doing: instances and their state, the mailbox, reminders, effects, broadcasts,
+dead letters, and the registered processes. It reads the same tables the
+runtime writes, so it needs no separate store and no agent.
+
+It is deliberately not loaded by `require "solid_objects"`. A worker process
+must not carry a web stack, and an application that never mounts the dashboard
+must not pay for it.
+
+## Mounting
+
+```ruby
+# config/routes.rb
+require "solid_objects/web"
+
+Rails.application.routes.draw do
+  mount SolidObjects::Web => "/solid_objects/dashboard"
+end
+```
+
+Mount it inside the application routes so the Rails session middleware runs
+first. The dashboard needs a Rack session for CSRF protection and refuses a
+state changing request without one.
+
+The dashboard and the engine are separate mounts. Mount the engine as well if
+the application uses reactive ERB, and give each one its own path:
+
+```ruby
+mount SolidObjects::Engine => "/solid_objects"
+mount SolidObjects::Web => "/solid_objects/dashboard"
+```
+
+In a bare Rack application, supply the session middleware yourself:
+
+```ruby
+use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: true
+run SolidObjects::Web
+```
+
+## Authorization
+
+Every page asks `configuration.authorize_administration` before its handler
+runs. That policy denies by default, so a mount alone exposes nothing. A route
+declared without a policy raises at load time, which is why a new page cannot
+reach the actor tables before an application has said who may read it.
+
+The block receives the route's own action and resource:
+
+| Page | `action` | `resource` | `resource_id` |
+| --- | --- | --- | --- |
+| Dashboard, `GET /stats`, `HEAD /` | `index` | `dashboard` | none |
+| Instance list | `index` | `instances` | none |
+| Instance detail | `show` | `instances` | instance id |
+| Pause an instance | `pause` | `instances` | instance id |
+| Resume an instance | `resume` | `instances` | instance id |
+| Mailbox | `index` | `messages` | none |
+| Message detail | `show` | `messages` | message id |
+| Reminders | `index` | `reminders` | none |
+| Effects | `index` | `effects` | none |
+| Broadcasts | `index` | `broadcasts` | none |
+| Dead letter list | `index` | `dead_letters` | none |
+| Dead letter detail | `show` | `dead_letters` | dead letter id |
+| Retry a dead letter | `retry` | `dead_letters` | dead letter id |
+| Processes | `index` | `processes` | none |
+
+`authorization_context:` is the request object. It answers `request`,
+`session`, and `env`, so a policy can read the signed-in operator the same way
+a controller does:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.authorize_administration = lambda do |action:, authorization_context:, **|
+    return false unless authorization_context.respond_to?(:session)
+
+    operator = Operator.find_by(id: authorization_context.session[:operator_id])
+    return false unless operator&.administrator?
+
+    action == "index" || action == "show" || operator.may_write_runtime?
+  end
+end
+```
+
+The command line reaches the same policy with `{ source: "cli" }` rather than
+a request, which is why the example checks what the context answers before
+reading a session from it.
+
+## Pages
+
+**Dashboard.** Totals per subsystem, the registered processes, and the most
+recent dead letters. The summary bar appears on every page and can poll
+`GET /stats` for the same numbers; nothing else on the page refreshes, because
+a table that reloads under an operator who is reading it is worse than a stale
+one.
+
+**Instances.** Filter by actor type and by an actor id substring. Each row
+shows the lease state: `idle`, `activated`, `expired`, or `paused`. The detail
+page shows committed state, the ready and claimed mailbox, message history,
+reminders, effects, broadcasts, and dead letters for that identity.
+
+**Mailbox.** The ready and claimed messages across every identity, oldest
+first. Mailbox lag on the summary bar is the age of the oldest message that is
+already due, which is how far behind the workers are.
+
+**Reminders, effects, broadcasts, processes.** Status filtered lists.
+
+## Charts
+
+The dashboard draws three charts: instances per actor type, mailbox depth, and
+a stacked view of effects, broadcasts, and reminders by status. Each canvas
+carries its own numbers in a `data-chart-values` attribute, so the page needs
+no inline script and no request to draw. Mailbox depth and the status chart
+redraw when the Live poller reports new totals, because `/stats` already
+carries those numbers. The instance chart does not: `/stats` does not group by
+actor type, and adding that would put a `GROUP BY` on every poll.
+
+Chart.js comes from a CDN with a subresource integrity hash, so a compromised
+CDN cannot substitute other code, and the CDN host is the only external origin
+the content security policy names.
+
+A deployment with no outbound network access should vendor the file:
+
+```ruby
+SolidObjects::Web.chart_library_url = "/javascripts/chart.umd.min.js"
+SolidObjects::Web.chart_library_integrity = nil
+```
+
+A path below the mount is served from the dashboard's own asset directory and
+needs no policy exception. Setting the URL to `nil` renders the dashboard
+without charts and names no external origin at all.
+
+Set these before the first request. The middleware stack and the compiled
+templates are built once and cached.
+
+**Dead letters.** The exception, its message, and its backtrace, with a retry
+button.
+
+## Actions
+
+The dashboard changes only two things.
+
+**Retry a dead letter** goes through `SolidObjects.dead_letters.retry`, which
+enqueues the original operation under an idempotency key. Pressing it twice
+produces one message rather than two.
+
+A retry re-enters the mailbox, which refuses work the runtime cannot accept: an
+actor class that no longer exists, a full mailbox, a payload over the cap. The
+dashboard renders the dead letter again with the reason and a 422 status,
+rather than failing the request.
+
+**Pause an instance** sets `paused_at`, and the activation manager stops
+claiming that identity. Two consequences matter:
+
+- A pass already in flight finishes its turn. Pause is not a stop.
+- A synchronous caller waiting on a paused instance times out rather than
+  receiving a result, because nothing will execute its message.
+
+Resume clears the column and the mailbox drains in sequence order.
+
+## Extensions
+
+An extension adds pages by declaring routes on the application class. Its
+routes carry an authorization policy like every other route:
+
+```ruby
+module Tenants
+  def self.registered(application)
+    application.get "/tenants", policy: { action: "index", resource: "tenants" } do
+      @tenants = Tenant.order(:name)
+      erb(:tenants)
+    end
+  end
+end
+
+SolidObjects::Web.register(
+  Tenants,
+  tab: "Tenants",
+  path: "/tenants",
+  views: File.expand_path("../web/views", __dir__)
+)
+```
+
+A registered view directory is searched before the packaged one, so an
+application can replace a single page without forking the gem. A template
+reads its arguments from `locals`, and a replacement `layout.erb` renders the
+page it wraps with `locals.fetch(:content)`.
+
+Add Rack middleware in front of the dashboard with `SolidObjects::Web.use`,
+for example to require HTTP basic authentication in an environment that has no
+session-backed operator.
+
+## Cost
+
+The summary bar issues one grouped count per subsystem on every page, and each
+list page counts its own relation to page it. That is a fixed set of indexed
+aggregate queries, not a scan proportional to actor traffic, but it is not
+free: do not put the dashboard behind an uptime monitor that loads the whole
+page on an interval. `HEAD /` exists for that. It touches one table and
+returns no body.

data/docs/database-schema.md

@@ -92,10 +92,11 @@ Status/availability/ID drives delivery; completion/ID drives cleanup.
 ### `broadcasts`
 
 Durable observable-change outbox. The unique message/observable key prevents
-duplicate rows for one actor turn. Rows contain the observable JSON value, or
-`{}` for an invalidation-only observable, plus message/instance references used to derive invalidation metadata, never
-personalized rendered HTML. Claim and delivery indexes support retries and
-cleanup.
+duplicate rows for one actor turn. Rows contain `{}` for the default
+invalidation-only observable, or the observable JSON value after an explicit
+`broadcast: :value` opt-in, plus message/instance references used to derive
+invalidation metadata, never personalized rendered HTML. Claim and delivery
+indexes support retries and cleanup.
 
 ### `dead_letters`
 

data/docs/development.md

@@ -140,6 +140,7 @@ COUNT=500 CONCURRENCY=4 bundle exec ruby -Ilib benchmark/concurrent_actors.rb
 COUNT=100 bundle exec ruby -Ilib benchmark/sync_latency.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/activation_cache.rb
 bundle exec ruby -Ilib benchmark/query_count.rb
+bundle exec ruby -Ilib benchmark/idle_polling.rb
 ```
 
 SQLite is the default. Set `SOLID_OBJECTS_DATABASE_URL` to benchmark a dedicated

data/docs/operations.md

@@ -69,6 +69,7 @@ Important controls include:
 - `lease_duration`
 - `lease_renewal_interval`
 - `polling_interval`
+- `idle_polling_interval`
 - `max_mailbox_length`
 - payload, state, and result byte limits
 - retry attempts and delay
@@ -81,6 +82,29 @@ Keep lease duration comfortably above renewal interval and expected database
 pause time. A handler can exceed the pass-duration budget because Ruby code is
 not safely preempted; alert on message duration and isolate untrusted work.
 
+## Polling and wake-up adapters
+
+`polling_interval` is the fast interval after work or a wake-up. Consecutive
+empty actor, effect, reminder, and broadcast passes double that role's wait up
+to `idle_polling_interval`, which defaults to one second. Actor workers clamp
+the ceiling to `lease_renewal_interval` while they may hold cached activations.
+Set the fast and idle values equal for a fixed cadence.
+
+The default wake-up interrupts waits only in the current Ruby process. When a
+live process record shows that the database is shared across processes and no
+adapter is configured, the runtime logs
+`solid_objects.polling_only_cross_process_wake_up` once. Configure
+`WakeUpAdapters::Postgresql` or `WakeUpAdapters::Redis` when separate processes
+need prompt delivery. Without one, newly committed work can wait up to the
+current idle polling interval.
+
+Each role exposes `current_polling_interval`.
+`solid_objects.polling.interval_changed` reports the role, reason, previous
+interval, and current interval. The polling-only warning is also emitted as
+`solid_objects.polling.only_cross_process_wake_up` instrumentation. Custom
+adapters should return `true` for a notification and `false` for a timeout; an
+older adapter that returns `nil` remains compatible and keeps the fast cadence.
+
 ## Graceful shutdown
 
 The supervisor requests shutdown, stops new claims, lets active loops return,

data/docs/realtime.md

@@ -13,12 +13,19 @@
 <% end %>
 ```
 
-Every observable gets a stable opaque DOM ID. Multiple values share the one
-actor subscription and Action Cable multiplexes actor subscriptions over the
-browser's physical WebSocket.
+Every value-broadcast observable gets a stable opaque DOM ID. Multiple values
+share the one actor subscription and Action Cable multiplexes actor
+subscriptions over the browser's physical WebSocket.
 
 Scalar observable calls such as `cart.items_count` render stable `<span>`
-targets. Their broadcast remains a direct escaped text replacement.
+targets. Their broadcast remains a direct escaped text replacement, and their
+declaration must explicitly opt in with `broadcast: :value`:
+
+```ruby
+observable :items_count, broadcast: :value do
+  items.sum { |item| item.fetch("quantity") }
+end
+```
 
 A reactive component declares one or more explicit observable dependencies.
 `actor.component(:summary, observes: ...)` resolves the host partial by
@@ -65,16 +72,12 @@ listed in `observes:` raises `UnknownComponentDependency`. This keeps
 invalidation correct and prevents a partial from silently depending on state
 that cannot wake it.
 
-Observable values are shared projections. By default, each changed value is
-stored in the broadcast outbox and can be sent as a scalar Turbo replacement to
-every subscriber that passes `authorize_subscription`. Authorization to the
-actor stream is not a per-viewer projection.
-
-For a component dependency whose value must never enter the durable outbox or
-Action Cable frame, declare it invalidation-only:
+Observables are invalidation-only by default. Their values never enter the
+durable outbox or Action Cable frame, so the ordinary declaration is the safe
+choice for component dependencies:
 
 ```ruby
-observable :player_one, broadcast: :invalidation do
+observable :player_one do
   player_in_seat(1)
 end
 ```
@@ -86,6 +89,10 @@ scalar value such as `actor.player_one`. The component endpoint reads the
 latest committed value and authorizes it again; subscriber-specific state
 belongs in `broadcast_payload`.
 
+Use `broadcast: :value` only for a shared projection that may be stored and
+sent to every subscriber that passes `authorize_subscription`. Authorization
+to the actor stream is not a per-viewer projection.
+
 ```erb
 <ul>
   <% actor.recent_messages.each do |message| %>
@@ -437,8 +444,9 @@ component key, locals, or DOM ID.
 ## Broadcast durability
 
 The actor's fenced commit compares observables before and after the turn and
-inserts one broadcast row per changed observable. Value-broadcast observables
-store the changed JSON value; invalidation-only observables store `{}`. The actor state, monotonic
+inserts one broadcast row per changed observable. Invalidation-only
+observables, the default, store `{}`. Observables declared with
+`broadcast: :value` store the changed JSON value. The actor state, monotonic
 `state_revision`, message completion, and broadcast rows commit atomically. A
 rolled-back or fenced-out turn therefore cannot invalidate a component.
 

data/docs/roadmap.md

@@ -24,10 +24,11 @@
   listed here while broken in that worker: the scheduler reached a constant the
   caller path happened to load, so reminders never fired in production and
   every in-process test still passed
-- Durable value or invalidation-only observable broadcasts, scalar Turbo
-  replacement, keyed ERB components, signed component locals, and authorized
-  replace or morph refresh. Invalidation-only observables retain component
-  change detection while storing and broadcasting no projected value
+- Durable invalidation-only observable broadcasts by default, explicit
+  `broadcast: :value` scalar Turbo replacement, keyed ERB components, signed
+  component locals, and authorized replace or morph refresh. Default
+  observables retain component change detection while storing and broadcasting
+  no projected value
 - Batched component refreshes: components sharing a signed `batch:` collapse to
   one browser request per revision, served as HTML frames in a JSON envelope
 - Personalized state payload broadcasts computed per subscriber under that
@@ -82,11 +83,14 @@
   What is not done is making any of them automatic. In-process signaling cannot
   cross process boundaries, so by default a commit in a web process does not
   wake a broadcast executor in a worker process and that delivery waits up to
-  `polling_interval`, 100 ms. An adapter removes that floor, measured at 103.7 ms
-  to 2.9 ms at p50 on PostgreSQL and 103.8 ms to 5.7 ms on Redis, but each stays
-  opt-in for a reason: the PostgreSQL adapter opens a connection per waiting
-  thread outside the pool and `LISTEN` does not survive a transaction-pooling
-  proxy such as PgBouncer, and Redis is not a dependency of this gem.
+  the current adaptive polling interval, up to the one-second
+  `idle_polling_interval` default. The runtime warns once when it observes this
+  topology without an adapter. An adapter removes that floor, measured before
+  adaptive polling at 103.7 ms to 2.9 ms at p50 on PostgreSQL and 103.8 ms to
+  5.7 ms on Redis, but each stays opt-in for a reason: the PostgreSQL adapter
+  opens a connection per waiting thread outside the pool and `LISTEN` does not
+  survive a transaction-pooling proxy such as PgBouncer, and Redis is not a
+  dependency of this gem.
   `WakeUpAdapters.for` selects notifications on PostgreSQL and the in-process
   default elsewhere; it never selects Redis. An application that configures
   nothing keeps polling, and MySQL applications keep polling unless they
@@ -107,8 +111,25 @@
   handing the block a raw Cable connection.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
-- Administration: actor and dead-letter views plus policy hooks exist; richer
-  filtering, audit records, and bulk-safe tools do not.
+- Administration: `SolidObjects::Web` is a mountable Rack dashboard covering
+  instances, mailbox, reminders, effects, broadcasts, dead letters, and
+  processes, with actor-type and actor-id filtering, status filters, paging, a
+  polled stats endpoint, Chart.js charts, and extension registration. The chart
+  library is fetched from a CDN with a subresource integrity hash, which a
+  deployment without outbound network access must replace with a vendored copy
+  or turn off. Every route declares its
+  own administration policy and a route declared without one raises at load
+  time, so the deny-by-default posture is enforced by construction rather than
+  by remembering to add a check. It changes only two things: an idempotent dead
+  letter retry and instance pause/resume. What does not exist is audit records
+  of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
+  because `DeadLetterManager` exposes no bulk operation. Pause is an operator
+  brake and not a stop, since a pass already in flight finishes its turn and a
+  synchronous caller waiting on a paused instance times out. The page cost was
+  reasoned about rather than measured: the summary bar issues a fixed set of
+  indexed aggregate queries per page, which is why `HEAD /` exists for uptime
+  monitors, but no dashboard latency has been benchmarked against a large
+  table.
 
 ## Next milestones
 

data/docs/security.md

@@ -36,13 +36,13 @@ Opaque stream and DOM names reduce accidental disclosure but do not replace
 authorization. Signed stream tokens are readable by their recipient and prove
 integrity only.
 
-Every normal observable value is stored in the broadcast outbox and can reach
-every subscriber that passes `authorize_subscription` for the actor. Never put
-credentials, session identifiers, private cards, hidden library order, or any
-other subscriber-specific state in a value-broadcast observable. Declare a
-component dependency with `broadcast: :invalidation` when only change metadata
-may cross the shared stream, or use `broadcast_payload` for a projection that
-must be computed separately for each authorized connection.
+Observables are invalidation-only by default, so their durable rows and shared
+actor stream carry no projected value. `broadcast: :value` deliberately stores
+the value in the broadcast outbox and may send it to every subscriber that
+passes `authorize_subscription` for the actor. Never opt credentials, session
+identifiers, private cards, hidden library order, or any other
+subscriber-specific state into value broadcasting. Use `broadcast_payload` for
+a projection that must be computed separately for each authorized connection.
 
 ## Serialization
 

data/examples/application/README.md

@@ -10,8 +10,8 @@ key. The chat actor also gives every submitted chat message a caller-generated
 message ID and checks that ID in durable actor state, because actor handlers may
 be redelivered.
 
-The views demonstrate scalar observable replacement and a live chat-message
-ERB component. The chat component receives `recent_messages` as an ordinary
-Ruby array, rerenders its `<ol>` after committed changes, and refreshes through
-the authenticated host request context. Turbo append intents remain roadmap
-work.
+The views demonstrate explicit `broadcast: :value` scalar replacement and a
+default invalidation-only chat-message ERB component. The chat component
+receives `recent_messages` as an ordinary Ruby array, rerenders its `<ol>` after
+committed changes, and refreshes through the authenticated host request
+context. Turbo append intents remain roadmap work.

data/examples/application/app/actors/chat_room_actor.rb

@@ -6,7 +6,7 @@ class ChatRoomActor < SolidObjects::Actor
   attribute :members, default: -> { [] }
   attribute :recent_messages, default: -> { [] }
 
-  observable :presence do
+  observable :presence, broadcast: :value do
     members.length
   end
 

data/examples/application/app/actors/shopping_cart_actor.rb

@@ -5,11 +5,11 @@ class ShoppingCartActor < SolidObjects::Actor
   attribute :checkout_status, default: "open"
   attribute :payment_id
 
-  observable :items_count do
+  observable :items_count, broadcast: :value do
     items.sum { |item| item.fetch("quantity") }
   end
 
-  observable :subtotal_cents do
+  observable :subtotal_cents, broadcast: :value do
     items.sum do |item|
       item.fetch("quantity") * item.fetch("unit_price_cents")
     end

data/lib/solid_objects/actor.rb

@@ -53,7 +53,7 @@ module SolidObjects
       end
 
       # @rbs (Symbol | String, ?broadcast: Symbol) ?{ () -> untyped } -> ActorDefinition::Handler
-      def observable(name, broadcast: :value, &block)
+      def observable(name, broadcast: :invalidation, &block)
         definition.add_observable(name, block, broadcast:)
       end
 

data/lib/solid_objects/broadcast_executor.rb

@@ -1,11 +1,14 @@
 # rbs_inline: enabled
 
+require "solid_objects/polling_backoff"
+
 module SolidObjects
   class BroadcastExecutor
     # @rbs @process_registry: ProcessRegistry
     # @rbs @database_adapter: DatabaseAdapter
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
     def initialize(
@@ -17,6 +20,17 @@ module SolidObjects
       process_registry.register(kind: "broadcast")
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: SolidObjects.configuration.polling_interval,
+        maximum_interval: SolidObjects.configuration.idle_polling_interval,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "broadcasts",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> bool
@@ -46,11 +60,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         worked = run_once
-        next if worked
-
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        if worked
+          polling_backoff.reset(:work)
+          next
+        end
+
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -72,9 +98,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :database_adapter
+    attr_reader :process_registry, :database_adapter, :polling_backoff
 
     # @rbs () -> Broadcast?
     def claim_next

data/lib/solid_objects/configuration.rb

@@ -4,6 +4,7 @@ module SolidObjects
   class Configuration
     # @rbs @table_name_prefix: String
     # @rbs @polling_interval: Float
+    # @rbs @idle_polling_interval: Float
     # @rbs @sync_polling_interval: Float
     # @rbs @lease_duration: Float
     # @rbs @lease_renewal_interval: Float
@@ -49,6 +50,7 @@ module SolidObjects
 
     attr_accessor :table_name_prefix,
       :polling_interval,
+      :idle_polling_interval,
       :sync_polling_interval,
       :lease_duration,
       :lease_renewal_interval,
@@ -99,6 +101,7 @@ module SolidObjects
     def initialize
       @table_name_prefix = "solid_objects_"
       @polling_interval = 0.1
+      @idle_polling_interval = 1.0
       @sync_polling_interval = 0.05
       @lease_duration = 30.0
       @lease_renewal_interval = 10.0
@@ -241,6 +244,7 @@ module SolidObjects
     def positive_values
       {
         polling_interval:,
+        idle_polling_interval:,
         sync_polling_interval:,
         lease_duration:,
         lease_renewal_interval:,

data/lib/solid_objects/effect_executor.rb

@@ -1,5 +1,7 @@
 # rbs_inline: enabled
 
+require "solid_objects/polling_backoff"
+
 module SolidObjects
   EffectContext = Data.define(:id, :attempt, :source_message_id, :actor_type, :actor_id)
 
@@ -10,6 +12,7 @@ module SolidObjects
     # @rbs @database_adapter: DatabaseAdapter
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry, ?database_adapter: DatabaseAdapter) -> void
     def initialize(
@@ -21,6 +24,17 @@ module SolidObjects
       process_registry.register(kind: "effect")
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: SolidObjects.configuration.polling_interval,
+        maximum_interval: SolidObjects.configuration.idle_polling_interval,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "effects",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> bool
@@ -50,11 +64,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         worked = run_once
-        next if worked
+        if worked
+          polling_backoff.reset(:work)
+          next
+        end
 
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -76,9 +102,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :database_adapter
+    attr_reader :process_registry, :database_adapter, :polling_backoff
 
     # @rbs () -> Effect?
     def claim_next