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
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/*
* Phusion Passenger - http://www.modrails.com/
* Copyright (c) 2008, 2009 Phusion
*
* "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#ifndef _PASSENGER_APPLICATION_POOL_H_
#define _PASSENGER_APPLICATION_POOL_H_
#include <boost/shared_ptr.hpp>
#include <sys/types.h>
#include "Application.h"
#include "PoolOptions.h"
namespace Passenger {
using namespace std;
using namespace boost;
/**
* A persistent pool of Applications.
*
* Spawning application instances, especially Ruby on Rails ones, is a very expensive operation.
* Despite best efforts to make the operation less expensive (see SpawnManager),
* it remains expensive compared to the cost of processing an HTTP request/response.
* So, in order to solve this, some sort of caching/pooling mechanism will be required.
* ApplicationPool provides this.
*
* Normally, one would use SpawnManager to spawn a new RoR/Rack application instance,
* then use Application::connect() to create a new session with that application
* instance, and then use the returned Session object to send the request and
* to read the HTTP response. ApplicationPool replaces the first step with
* a call to Application::get(). For example:
* @code
* ApplicationPool pool = some_function_which_creates_an_application_pool();
*
* // Connect to the application and get the newly opened session.
* Application::SessionPtr session(pool->get("/home/webapps/foo"));
*
* // Send the request headers and request body data.
* session->sendHeaders(...);
* session->sendBodyBlock(...);
* // Done sending data, so we shutdown the writer stream.
* session->shutdownWriter();
*
* // Now read the HTTP response.
* string responseData = readAllDataFromSocket(session->getStream());
* // Done reading data, so we shutdown the reader stream.
* session->shutdownReader();
*
* // This session has now finished, so we close the session by resetting
* // the smart pointer to NULL (thereby destroying the Session object).
* session.reset();
*
* // We can connect to an Application multiple times. Just make sure
* // the previous session is closed.
* session = app->connect("/home/webapps/bar")
* @endcode
*
* Internally, ApplicationPool::get() will keep spawned applications instances in
* memory, and reuse them if possible. It wil* @throw l try to keep spawning to a minimum.
* Furthermore, if an application instance hasn't been used for a while, it
* will be automatically shutdown in order to save memory. Restart requests are
* honored: if an application has the file 'restart.txt' in its 'tmp' folder,
* then get() will shutdown existing instances of that application and spawn
* a new instance (this is useful when a new version of an application has been
* deployed). And finally, one can set a hard limit on the maximum number of
* applications instances that may be spawned (see ApplicationPool::setMax()).
*
* Note that ApplicationPool is just an interface (i.e. a pure virtual class).
* For concrete classes, see StandardApplicationPool and ApplicationPoolServer.
* The exact pooling algorithm depends on the implementation class.
*
* @ingroup Support
*/
class ApplicationPool {
public:
virtual ~ApplicationPool() {};
/**
* Checks whether this ApplicationPool object is still connected to the
* ApplicationPool server.
*
* If that's not the case, then one should reconnect to the ApplicationPool server.
*
* This method is only meaningful for instances of type ApplicationPoolServer::Client.
* The default implementation always returns true.
*/
virtual bool connected() const {
return true;
}
/**
* Open a new session with the application specified by <tt>PoolOptions.appRoot</tt>.
* See the class description for ApplicationPool, as well as Application::connect(),
* on how to use the returned session object.
*
* Internally, this method may either spawn a new application instance, or use
* an existing one.
*
* @param options An object containing information on which application to open
* a session with, as well as spawning details. Spawning details will be used
* if the pool decides that spawning a new application instance is necessary.
* See SpawnManager and PoolOptions for details.
* @return A session object.
* @throw SpawnException An attempt was made to spawn a new application instance, but that attempt failed.
* @throw BusyException The application pool is too busy right now, and cannot
* satisfy the request. One should either abort, or try again later.
* @throw IOException Something else went wrong.
* @throw boost::thread_interrupted
* @throws Anything thrown by options.environmentVariables->getItems().
* @note Applications are uniquely identified with the application root
* string. So although <tt>appRoot</tt> does not have to be absolute, it
* should be. If one calls <tt>get("/home/foo")</tt> and
* <tt>get("/home/../home/foo")</tt>, then ApplicationPool will think
* they're 2 different applications, and thus will spawn 2 application instances.
*/
virtual Application::SessionPtr get(const PoolOptions &options) = 0;
/**
* Convenience shortcut for calling get() with default spawn options.
*/
virtual Application::SessionPtr get(const string &appRoot) {
return get(PoolOptions(appRoot));
}
/**
* Clear all application instances that are currently in the pool.
*
* This method is used by unit tests to verify that the implementation is correct,
* and thus should not be called directly.
*/
virtual void clear() = 0;
virtual void setMaxIdleTime(unsigned int seconds) = 0;
/**
* Set a hard limit on the number of application instances that this ApplicationPool
* may spawn. The exact behavior depends on the used algorithm, and is not specified by
* these API docs.
*
* It is allowed to set a limit lower than the current number of spawned applications.
*/
virtual void setMax(unsigned int max) = 0;
/**
* Get the number of active applications in the pool.
*
* This method exposes an implementation detail of the underlying pooling algorithm.
* It is used by unit tests to verify that the implementation is correct,
* and thus should not be called directly.
*/
virtual unsigned int getActive() const = 0;
/**
* Get the number of active applications in the pool.
*
* This method exposes an implementation detail of the underlying pooling algorithm.
* It is used by unit tests to verify that the implementation is correct,
* and thus should not be called directly.
*/
virtual unsigned int getCount() const = 0;
/**
* Set a hard limit on the number of application instances that a single application
* may spawn in this ApplicationPool. The exact behavior depends on the used algorithm,
* and is not specified by these API docs.
*
* It is allowed to set a limit lower than the current number of spawned applications.
*/
virtual void setMaxPerApp(unsigned int max) = 0;
/**
* Get the process ID of the spawn server that is used.
*
* This method exposes an implementation detail. It is used by unit tests to verify
* that the implementation is correct, and thus should not be used directly.
*/
virtual pid_t getSpawnServerPid() const = 0;
};
typedef shared_ptr<ApplicationPool> ApplicationPoolPtr;
}; // namespace Passenger
#endif /* _PASSENGER_APPLICATION_POOL_H_ */
|
