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: GRACEFUL_STOP) ⇒ Controller

Initialize the controller.



38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/async/container/controller.rb', line 38

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

Instance Attribute Details

#container ⇒ Object (readonly)

The current container being managed by the controller.



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

def container
  @container
end

#container_class ⇒ Object (readonly)

The container class used by the controller.



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

def container_class
  @container_class
end

#graceful_stop ⇒ Object (readonly)

The graceful stop flag used by the controller.



58
59
60
 
# File 'lib/async/container/controller.rb', line 58

def graceful_stop
  @graceful_stop
end

#notify ⇒ Object (readonly)

The notify client used by the controller.



52
53
54
 
# File 'lib/async/container/controller.rb', line 52

def notify
  @notify
end

Instance Method Details

#create_container ⇒ Object

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



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

def create_container
	@container_class.new(policy: self.make_policy)
end

#make_policy ⇒ Object

Create a policy for managing child lifecycle events. Can be overridden by a sub-class to provide a custom policy.



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

def make_policy
	Policy::DEFAULT
end

#reload ⇒ Object

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



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/async/container/controller.rb', line 190

def reload
	@notify&.reloading!
	
	Console.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.info(self, "Waiting for startup...")
	@container.wait_until_ready
	Console.info(self, "Finished startup.")
	
	if @container.failed?
		@notify.error!("Container failed to reload!")
		
		raise SetupError, @container
	else
		@notify&.ready!(size: @container.size, status: "Running with #{@container.size} children.")
	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.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
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
183
184
185
186
187
 
# File 'lib/async/container/controller.rb', line 138

def restart
	if @container
		@notify&.restarting!
		
		Console.info(self, "Restarting container...")
	else
		Console.info(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.info(self, "Waiting for startup...")
	container.wait_until_ready
	Console.info(self, "Finished startup.")
	
	if container.failed?
		@notify&.error!("Container failed to start!")
		
		raise SetupError, container
	end
	
	# The following swap should be atomic:
	old_container = @container
	@container = container
	container = nil
	
	if old_container
		Console.info(self, "Stopping old container...")
		old_container&.stop(@graceful_stop)
	end
	
	@notify&.ready!(size: @container.size, status: "Running with #{@container.size} children.")
rescue => error
	raise
ensure
	# If we are leaving this function with an exception, kill the container:
	if container
		Console.warn(self, "Stopping failed container...", exception: error)
		container.stop(false)
	end
end

#run ⇒ Object

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



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/async/container/controller.rb', line 216

def run
	@notify&.status!("Initializing controller...")
	
	with_signal_handlers do
		self.start
		
		while @container&.running?
			begin
				@container.wait
			rescue SignalException => exception
				if handler = @signals[exception.signo]
					begin
						handler.call
					rescue SetupError => error
						Console.error(self, error)
					end
				else
					raise
				end
			end
		end
	end
rescue Interrupt
	self.stop
rescue Terminate
	self.stop(false)
ensure
	self.stop(false)
end

#running? ⇒ Boolean

Whether the controller has a running container.

Returns:

  • (Boolean) 


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

def running?
	!!@container
end

#setup(container) ⇒ Object

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



114
115
116
117
 
# File 'lib/async/container/controller.rb', line 114

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.



120
121
122
123
124
125
126
127
 
# File 'lib/async/container/controller.rb', line 120

def start
	unless @container
		Console.info(self, "Controller starting...")
		self.restart
	end
	
	Console.info(self, "Controller started.")
end

#state_string ⇒ Object

The state of the controller.



65
66
67
68
69
70
71
 
# File 'lib/async/container/controller.rb', line 65

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

#stop(graceful = @graceful_stop) ⇒ Object

Stop the container if it’s running.



131
132
133
134
 
# File 'lib/async/container/controller.rb', line 131

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

#to_s ⇒ Object

A human readable representation of the controller.



75
76
77
 
# File 'lib/async/container/controller.rb', line 75

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

#trap(signal, &block) ⇒ Object

Trap the specified signal.



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

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

#wait ⇒ Object

Wait for the underlying container to start.



107
108
109
 
# File 'lib/async/container/controller.rb', line 107

def wait
	@container&.wait
end