-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.restart.html
150 lines (118 loc) · 9.21 KB
/
file.restart.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
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
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>File: Restart — Puma master</title>
<link rel='stylesheet' type='text/css' href='../css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='../css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='../css/y_style.css' />
<link rel='stylesheet' type='text/css' href='../css/y_list.css' />
<link rel='stylesheet' type='text/css' href='../css/y_color.css' />
<script type='text/javascript'>
var pathId = "restart",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='../js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='../js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a id='home_no_xhr' href='/'>Home</a> »
<a href='.'>Puma master</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>File: Restart ▲</a></span>
</div>
<a id='list_href' href="class_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<p><a href="Puma.html" title="Puma (module)"><code>Puma</code></a> provides three distinct kinds of restart operations, each for different use cases. This document describes "hot restarts" and "phased restarts." The third kind of restart operation is called "refork" and is described in the documentation for <a href="file.fork_worker.html"><code>fork_worker</code></a>.</p>
<h2>Hot restart</h2>
<p>To perform a "hot" restart, <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> performs an <code>exec</code> operation to start the process up again, so no memory is shared between the old process and the new process. As a result, it is safe to issue a restart at any place where you would manually stop <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> and start it again. In particular, it is safe to upgrade <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> itself using a hot restart.</p>
<p>If the new process is unable to load, it will simply exit. You should therefore run <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> under a process monitor when using it in production.</p>
<h3>How-to</h3>
<p>Any of the following will cause a <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> server to perform a hot restart: </p>
<ul>
<li>Send the <code>puma</code> process the <code>SIGUSR2</code> signal</li>
<li>Issue a <code>GET</code> request to the <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> status/control server with the path <code>/restart</code></li>
<li>Issue <code>pumactl restart</code> (this uses the control server method if available, otherwise sends the <code>SIGUSR2</code> signal to the process)</li>
</ul>
<h3>Supported configurations</h3>
<ul>
<li>Works in cluster mode and single mode</li>
<li>Supported on all platforms</li>
</ul>
<h3>Client experience</h3>
<ul>
<li>All platforms: clients with an in-flight request are served responses before the connection is closed gracefully. <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> gracefully disconnects any idle HTTP persistent connections before restarting.</li>
<li>On MRI or TruffleRuby on Linux and BSD: Clients who connect just before the server restarts may experience increased latency while the server stops and starts again, but their connections will not be closed prematurely.</li>
<li>On Windows and JRuby: Clients who connect just before a restart may experience "connection reset" errors.</li>
</ul>
<h3>Additional notes</h3>
<ul>
<li>The newly started <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> process changes its current working directory to the directory specified by the <code>directory</code> option. If <code>directory</code> is set to symlink, this is automatically re-evaluated, so this mechanism can be used to upgrade the application.</li>
<li>Only one version of the application is running at a time.</li>
<li><code>on_restart</code> is invoked just before the server shuts down. This can be used to clean up resources (like long-lived database connections) gracefully. Since Ruby 2.0, it is not typically necessary to explicitly close file descriptors on restart. This is because any file descriptor opened by Ruby will have the <code>FD_CLOEXEC</code> flag set, meaning that file descriptors are closed on <code>exec</code>. <code>on_restart</code> is useful, though, if your application needs to perform any more graceful protocol-specific shutdown procedures before closing connections.</li>
</ul>
<h2>Phased restart</h2>
<p>Phased restarts replace all running workers in a <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> cluster. This is a useful way to upgrade the application that <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> is serving gracefully. A phased restart works by first killing an old worker, then starting a new worker, waiting until the new worker has successfully started before proceeding to the next worker. This process continues until all workers are replaced. The master process is not restarted.</p>
<h3>How-to</h3>
<p>Any of the following will cause a <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> server to perform a phased restart: </p>
<ul>
<li>Send the <code>puma</code> process the <code>SIGUSR1</code> signal</li>
<li>Issue a <code>GET</code> request to the <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> status/control server with the path <code>/phased-restart</code></li>
<li>Issue <code>pumactl phased-restart</code> (this uses the control server method if available, otherwise sends the <code>SIGUSR1</code> signal to the process)</li>
</ul>
<h3>Supported configurations</h3>
<ul>
<li>Works in cluster mode only</li>
<li>To support upgrading the application that <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> is serving, ensure <code>prune_bundler</code> is enabled and that <code>preload_app!</code> is disabled</li>
<li>Supported on all platforms where cluster mode is supported</li>
</ul>
<h3>Client experience</h3>
<ul>
<li>In-flight requests are always served responses before the connection is closed gracefully</li>
<li>Idle persistent connections are gracefully disconnected</li>
<li>New connections are not lost, and clients will not experience any increase in latency (as long as the number of configured workers is greater than one)</li>
</ul>
<h3>Additional notes</h3>
<ul>
<li>When a phased restart begins, the <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> master process changes its current working directory to the directory specified by the <code>directory</code> option. If <code>directory</code> is set to symlink, this is automatically re-evaluated, so this mechanism can be used to upgrade the application.</li>
<li>On a single server, it's possible that two versions of the application are running concurrently during a phased restart.</li>
<li><code>on_restart</code> is not invoked</li>
<li>Phased restarts can be slow for <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> clusters with many workers. Hot restarts often complete more quickly, but at the cost of increased latency during the restart.</li>
<li>Phased restarts cannot be used to upgrade any gems loaded by the <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> master process, including <code>puma</code> itself, anything in <code>extra_runtime_dependencies</code>, or dependencies thereof. Upgrading other gems is safe.</li>
<li>If you remove the gems from old releases as part of your deployment strategy, there are additional considerations. Do not put any gems into <code>extra_runtime_dependencies</code> that have native extensions or have dependencies that have native extensions (one common example is <code>puma_worker_killer</code> and its dependency on <code>ffi</code>). Workers will fail on boot during a phased restart. The underlying issue is recorded in <a href="https://github.com/rubygems/rubygems/issues/4004">an issue on the rubygems project</a>. Hot restarts are your only option here if you need these dependencies.</li>
</ul>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>