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

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.

Parameters:

Returns:

  • (String)


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.

Parameters:

  • value (Boolean)

Returns:

  • (Boolean)


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=.

Returns:



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.

Returns:

  • (Array<String>)


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.

Returns:

  • (Boolean)


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).

Parameters:

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    when a service of the same name is registered



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).

Parameters:

Returns:



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.

Parameters:

Returns:

  • (Integer) —

    how many services’ service_start returned true



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.

Parameters:

  • config (Config)
  • names (Array<String>) —

    empty for everything

Returns:

  • (Integer) —

    how many services started something



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).

Returns:

  • (nil)


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.

Returns:

  • (nil)


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.

Parameters:

  • config (Config) —

    its feed_status_interval, feed_restart_limit and feed_restart_window

Returns:

  • (Boolean) —

    true when it started the thread



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!.

Returns:



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.

Parameters:

  • names (Array<String>)

Returns:

  • (String)


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.

Returns:

  • (Integer) —

    how many rows were deleted



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