Class: Async::Container::Controller

Inherits:
Object
  • Object
show all
Defined in:
lib/async/container/controller.rb

Overview

Manages the life-cycle of one or more containers in order to support a persistent system. e.g. a web server, job server or some other long running system.

Constant Summary collapse

SIGHUP = 
Signal.list["HUP"]
SIGINT = 
Signal.list["INT"]
SIGTERM = 
Signal.list["TERM"]
SIGUSR1 = 
Signal.list["USR1"]
SIGUSR2 = 
Signal.list["USR2"]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(notify: Notify.open!, container_class: Container, graceful_stop: true) ⇒ Controller

Initialize the controller.



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/async/container/controller.rb', line 25

def initialize(notify: Notify.open!, container_class: Container, graceful_stop: true)
  @container = nil
  @container_class = container_class
  
  if @notify = notify
    @notify.status!("Initializing...")
  end
  
  @signals = {}
  
  trap(SIGHUP) do
    self.restart
  end
  
  @graceful_stop = graceful_stop
end

Instance Attribute Details

#container ⇒ Object (readonly)

The current container being managed by the controller.



66
67
68
 
# File 'lib/async/container/controller.rb', line 66

def container
  @container
end

Instance Method Details

#create_container ⇒ Object

Create a container for the controller. Can be overridden by a sub-class.



71
72
73
 
# File 'lib/async/container/controller.rb', line 71

def create_container
  @container_class.new
end

#reload ⇒ Object

Reload the existing container. Children instances will be reloaded using ‘SIGHUP`.



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/async/container/controller.rb', line 157

def reload
  @notify&.reloading!
  
  Console.logger.info(self) {"Reloading container: #{@container}..."}
  
  begin
    self.setup(@container)
  rescue
    raise SetupError, container
  end
  
  # Wait for all child processes to enter the ready state.
  Console.logger.debug(self, "Waiting for startup...")
  
  @container.wait_until_ready
  
  Console.logger.debug(self, "Finished startup.")
  
  if @container.failed?
    @notify.error!("Container failed to reload!")
    
    raise SetupError, @container
  else
    @notify&.ready!
  end
end

#restart ⇒ Object

Restart the container. A new container is created, and if successful, any old container is terminated gracefully. This is equivalent to a blue-green deployment.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/async/container/controller.rb', line 108

def restart
  if @container
    @notify&.restarting!
    
    Console.logger.debug(self) {"Restarting container..."}
  else
    Console.logger.debug(self) {"Starting container..."}
  end
  
  container = self.create_container
  
  begin
    self.setup(container)
  rescue => error
    @notify&.error!(error.to_s)
    
    raise SetupError, container
  end
  
  # Wait for all child processes to enter the ready state.
  Console.logger.debug(self, "Waiting for startup...")
  container.wait_until_ready
  Console.logger.debug(self, "Finished startup.")
  
  if container.failed?
    @notify&.error!("Container failed to start!")
    
    container.stop(false)
    
    raise SetupError, container
  end
  
  # The following swap should be atomic:
  old_container = @container
  @container = container
  container = nil
  
  if old_container
    Console.logger.debug(self, "Stopping old container...")
    old_container&.stop(@graceful_stop)
  end
  
  @notify&.ready!
ensure
  # If we are leaving this function with an exception, try to kill the container:
  container&.stop(false)
end

#run ⇒ Object

Enter the controller run loop, trapping ‘SIGINT` and `SIGTERM`.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/async/container/controller.rb', line 185

def run
  # I thought this was the default... but it doesn't always raise an exception unless you do this explicitly.
  # We use `Thread.current.raise(...)` so that exceptions are filtered through `Thread.handle_interrupt` correctly.
  interrupt_action = Signal.trap(:INT) do
    # $stderr.puts "Received INT signal, terminating...", caller
    ::Thread.current.raise(Interrupt)
  end
  
  terminate_action = Signal.trap(:TERM) do
    # $stderr.puts "Received TERM signal, terminating...", caller
    ::Thread.current.raise(Terminate)
  end
  
  hangup_action = Signal.trap(:HUP) do
    # $stderr.puts "Received HUP signal, restarting...", caller
    ::Thread.current.raise(Hangup)
  end
  
  self.start
  
  while @container&.running?
    begin
      @container.wait
    rescue SignalException => exception
      if handler = @signals[exception.signo]
        begin
          handler.call
        rescue SetupError => error
          Console.logger.error(self) {error}
        end
      else
        raise
      end
    end
  end
rescue Interrupt
  self.stop
rescue Terminate
  self.stop(false)
ensure
  self.stop(false)
  
  # Restore the interrupt handler:
  Signal.trap(:INT, interrupt_action)
  Signal.trap(:TERM, terminate_action)
  Signal.trap(:HUP, hangup_action)
end

#running? ⇒ Boolean

Whether the controller has a running container.

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/async/container/controller.rb', line 77

def running?
  !!@container
end

#setup(container) ⇒ Object

Spawn container instances into the given container. Should be overridden by a sub-class.



89
90
91
92
 
# File 'lib/async/container/controller.rb', line 89

def setup(container)
  # Don't do this, otherwise calling super is risky for sub-classes:
  # raise NotImplementedError, "Container setup is must be implemented in derived class!"
end

#start ⇒ Object

Start the container unless it’s already running.



95
96
97
 
# File 'lib/async/container/controller.rb', line 95

def start
  self.restart unless @container
end

#state_string ⇒ Object

The state of the controller.



44
45
46
47
48
49
50
 
# File 'lib/async/container/controller.rb', line 44

def state_string
  if running?
    "running"
  else
    "stopped"
  end
end

#stop(graceful = @graceful_stop) ⇒ Object

Stop the container if it’s running.



101
102
103
104
 
# File 'lib/async/container/controller.rb', line 101

def stop(graceful = @graceful_stop)
  @container&.stop(graceful)
  @container = nil
end

#to_s ⇒ Object

A human readable representation of the controller.



54
55
56
 
# File 'lib/async/container/controller.rb', line 54

def to_s
  "#{self.class} #{state_string}"
end

#trap(signal, &block) ⇒ Object

Trap the specified signal.



61
62
63
 
# File 'lib/async/container/controller.rb', line 61

def trap(signal, &block)
  @signals[signal] = block
end

#wait ⇒ Object

Wait for the underlying container to start.



82
83
84
 
# File 'lib/async/container/controller.rb', line 82

def wait
  @container&.wait
end