Module: Cybertrain::Background
- Defined in:
- cybertrain/background.rb,
cybertrain/background/supervisor.rb
Overview
Cybertrain::Background – services Application#serve starts and stops without application.rb requiring them.
A file that runs something long-lived beside the server (the WebSocket client’s subscriptions, cybertrain/websocket.rb) subclasses Service and registers an instance when it is required:
class FeedService < Cybertrain::Background::Service def service_name = “feeds” def service_start(config) = Feeds.start!(config) def service_stop = Feeds.stop! end Cybertrain::Background.register(FeedService.new)
Application#serve calls Background.start_all right after
Scheduler.start! (the database is connected, the port bound and
SPINEL_WORKERS set: spikes/NOTES.md rule 22) and Background.stop_all
right after Scheduler.stop!. ./<app> migrate, db ..., Main.command
and Test::Client never start them. The same pattern as
Net.tls_connector: a do-nothing default here, the real one in the file
that is required only by the programs that use it (so a program that
never opens a WebSocket does not link it).
Defined Under Namespace
Classes: Service
Class Method Summary collapse
-
.boot_problem(config) ⇒ String
The first registered service’s Service#service_problem, “” when none has one, or when Config#worker is off (nothing starts then).
-
.exit_on_feed_death=(value) ⇒ Boolean
Whether a feed that dies too often ends the process: true in a
feedsprocess (Application#run_feeds sets it for the role’s lifetime), false in aserverprocess, which serves requests and keeps restarting the feed. - .exit_on_feed_death? ⇒ Boolean
-
.feed_names ⇒ Array<String>
Every registered service’s Service#service_feed_names, in order.
-
.feeds_failed? ⇒ Boolean
True once the supervisor gave up on a feed in a
feedsprocess (the FATAL line is logged): the role’s main thread stops the feeds and exits with status 1. -
.register(service) ⇒ nil
Adds a service for Background.start_all to start.
-
.restart_backoff(restarts) ⇒ Integer
Seconds the supervisor waits before starting a dead feed again, given how many times it was restarted before: min(30, 2 ** restarts).
-
.start_all(config) ⇒ Integer
Starts every registered service, in registration order, unless Config#worker is off (
CYBERTRAIN_WORKER=0: the process that runs the background work is another one), and the feed supervisor (Background.supervise!) when a service with feeds started. -
.start_only(config, names) ⇒ Integer
Starts every registered service with Service#service_start_only, in registration order, and the feed supervisor as Background.start_all does: what
./<app> feeds [NAME...]runs. -
.stop_all ⇒ nil
Asks every registered service to end, in registration order, after stopping the feed supervisor (so a stopping feed is not restarted).
-
.stop_supervisor! ⇒ nil
Stops the supervisor thread and waits for it (at most 2 s).
-
.supervise!(config) ⇒ Boolean
Starts the supervisor thread, unless one runs.
-
.supervising? ⇒ Boolean
True between Background.supervise! and Background.stop_supervisor!.
-
.unknown_feed(names) ⇒ String
unknown feed "NAME" (registered: a, b)for the first ofnamesthat no service lists in Service#service_feed_names, “” when every one is known. -
.withdraw_status_all ⇒ Integer
Every registered service’s Service#service_withdraw_status, in order: what a
feedsprocess does after a clean stop.
Class Method Details
.boot_problem(config) ⇒ String
The first registered service’s Cybertrain::Background::Service#service_problem, “” when none has one, or when Config#worker is off (nothing starts then). Application#serve calls it before binding the port and fails the boot with it.
178 179 180 181 182 183 184 185 186 187 188 189 |
# File 'cybertrain/background.rb', line 178 def self.boot_problem(config) return "" unless config.worker i = 0 while i < SERVICES.size problem = SERVICES[i].service_problem return problem unless problem.empty? i += 1 end "" end |
.exit_on_feed_death=(value) ⇒ Boolean
Whether a feed that dies too often ends the process: true in a
feeds process (Application#run_feeds sets it for the role’s
lifetime), false in a server process, which serves requests and
keeps restarting the feed.
174 175 176 |
# File 'cybertrain/background/supervisor.rb', line 174 def self.exit_on_feed_death=(value) @exit_on_feed_death = value end |
.exit_on_feed_death? ⇒ Boolean
Returns see exit_on_feed_death=.
180 181 182 |
# File 'cybertrain/background/supervisor.rb', line 180 def self.exit_on_feed_death? @exit_on_feed_death end |
.feed_names ⇒ Array<String>
Every registered service’s Cybertrain::Background::Service#service_feed_names, in order.
234 235 236 237 238 239 240 241 242 |
# File 'cybertrain/background.rb', line 234 def self.feed_names out = Array.new(0) { "" } i = 0 while i < SERVICES.size SERVICES[i].service_feed_names.each { |name| out << name } i += 1 end out end |
.feeds_failed? ⇒ Boolean
True once the supervisor gave up on a feed in a feeds process (the
FATAL line is logged): the role’s main thread stops the feeds and
exits with status 1.
189 190 191 |
# File 'cybertrain/background/supervisor.rb', line 189 def self.feeds_failed? @feeds_failed end |
.register(service) ⇒ nil
Adds a service for start_all to start. Register before the server starts (when the file defining it is required).
153 154 155 156 157 158 159 |
# File 'cybertrain/background.rb', line 153 def self.register(service) name = service.service_name raise ArgumentError, "Background.register #{name.inspect}: already registered" if service_index(name) >= 0 SERVICES << service nil end |
.restart_backoff(restarts) ⇒ Integer
Seconds the supervisor waits before starting a dead feed again, given how many times it was restarted before: min(30, 2 ** restarts).
198 199 200 201 202 203 |
# File 'cybertrain/background/supervisor.rb', line 198 def self.restart_backoff(restarts) return 1 if restarts < 1 return 30 if restarts >= 5 2**restarts end |
.start_all(config) ⇒ Integer
Starts every registered service, in registration order, unless
Config#worker is off (CYBERTRAIN_WORKER=0: the process that runs
the background work is another one), and the feed supervisor
(supervise!) when a service with feeds started.
198 199 200 201 202 203 204 205 206 207 208 209 |
# File 'cybertrain/background.rb', line 198 def self.start_all(config) return 0 unless config.worker started = 0 i = 0 while i < SERVICES.size started += 1 if SERVICES[i].service_start(config) i += 1 end supervise!(config) if started > 0 && !feed_names.empty? started end |
.start_only(config, names) ⇒ Integer
Starts every registered service with Cybertrain::Background::Service#service_start_only, in
registration order, and the feed supervisor as start_all
does: what ./<app> feeds [NAME...] runs. Unlike
start_all it ignores Config#worker: the role was asked
for by name.
220 221 222 223 224 225 226 227 228 229 |
# File 'cybertrain/background.rb', line 220 def self.start_only(config, names) started = 0 i = 0 while i < SERVICES.size started += 1 if SERVICES[i].service_start_only(config, names) i += 1 end supervise!(config) if started > 0 && !feed_names.empty? started end |
.stop_all ⇒ nil
Asks every registered service to end, in registration order, after stopping the feed supervisor (so a stopping feed is not restarted).
291 292 293 294 295 296 297 298 299 |
# File 'cybertrain/background.rb', line 291 def self.stop_all stop_supervisor! i = 0 while i < SERVICES.size SERVICES[i].service_stop i += 1 end nil end |
.stop_supervisor! ⇒ nil
Stops the supervisor thread and waits for it (at most 2 s). Does nothing when none runs. stop_all calls it before stopping the services. A pass still running past the wait restarts nothing: the restart is checked against the stop under the lock.
138 139 140 141 142 143 144 145 146 147 148 149 |
# File 'cybertrain/background/supervisor.rb', line 138 def self.stop_supervisor! running = false SUPERVISOR_LOCK.synchronize do running = @supervising @supervising = false end return nil unless running thread = @supervisor_thread join_supervisor(thread) unless thread.nil? nil end |
.supervise!(config) ⇒ Boolean
Starts the supervisor thread, unless one runs. start_all and start_only call it when a service with feeds started.
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 |
# File 'cybertrain/background/supervisor.rb', line 116 def self.supervise!(config) generation = 0 SUPERVISOR_LOCK.synchronize do unless @supervising reset_supervisor! @supervising = true @supervisor_generation += 1 generation = @supervisor_generation end end return false if generation == 0 @supervisor_thread = spawn_supervisor(config, generation) true end |
.supervising? ⇒ Boolean
Returns true between supervise! and stop_supervisor!.
163 164 165 |
# File 'cybertrain/background/supervisor.rb', line 163 def self.supervising? @supervising end |
.unknown_feed(names) ⇒ String
unknown feed "NAME" (registered: a, b) for the first of names
that no service lists in Cybertrain::Background::Service#service_feed_names, “” when every
one is known.
250 251 252 |
# File 'cybertrain/background.rb', line 250 def self.unknown_feed(names) Background.unknown_name_in(names, feed_names) end |
.withdraw_status_all ⇒ Integer
Every registered service’s Cybertrain::Background::Service#service_withdraw_status, in
order: what a feeds process does after a clean stop.
277 278 279 280 281 282 283 284 285 |
# File 'cybertrain/background.rb', line 277 def self.withdraw_status_all removed = 0 i = 0 while i < SERVICES.size removed += SERVICES[i].service_withdraw_status i += 1 end removed end |