Passenger: AbstractSpawnManager.h Source File

- Main Page
- Modules
- Namespaces
- Classes
- Files

- File List

# AbstractSpawnManager.h

    00001 /*
    00002  *  Phusion Passenger - http://www.modrails.com/
    00003  *  Copyright (c) 2010 Phusion
    00004  *
    00005  *  "Phusion Passenger" is a trademark of Hongli Lai & Ninh Bui.
    00006  *
    00007  *  Permission is hereby granted, free of charge, to any person obtaining a copy
    00008  *  of this software and associated documentation files (the "Software"), to deal
    00009  *  in the Software without restriction, including without limitation the rights
    00010  *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    00011  *  copies of the Software, and to permit persons to whom the Software is
    00012  *  furnished to do so, subject to the following conditions:
    00013  *
    00014  *  The above copyright notice and this permission notice shall be included in
    00015  *  all copies or substantial portions of the Software.
    00016  *
    00017  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    00018  *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    00019  *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    00020  *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    00021  *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    00022  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    00023  *  THE SOFTWARE.
    00024  */
    00025 #ifndef _PASSENGER_ABSTRACT_SPAWN_MANAGER_H_
    00026 #define _PASSENGER_ABSTRACT_SPAWN_MANAGER_H_
    00027
    00028 #include <string>
    00029
    00030 #include <boost/shared_ptr.hpp>
    00031
    00032 #include <unistd.h>
    00033
    00034 #include "Process.h"
    00035 #include "PoolOptions.h"
    00036
    00037 namespace Passenger {
    00038
    00039 using namespace std;
    00040 using namespace boost;
    00041
    00042 /**
    00043  * @brief Spawning of application processes.
    00044  *
    00045  * An AbstractSpawnManager is responsible for spawning new application processes.
    00046  * Use the spawn() method to do so. AbstractSpawnManager is guaranteed to be thread-safe.
    00047  *
    00048  * AbstractSpawnManager is just an interface. There are two concrete implementations,
    00049  * namely SpawnManager and StubSpawnManager. The former is the one that's usually used,
    00050  * while the latter exists for unit testing purposes.
    00051  *
    00052  * @ingroup Support
    00053  */
    00054 class AbstractSpawnManager {
    00055 public:
    00056         virtual ~AbstractSpawnManager() { }
    00057
    00058         /**
    00059          * Spawn a new application process. Spawning details are to be passed
    00060          * via the <tt>options</tt> argument.
    00061          *
    00062          * If the spawn server died during the spawning process, then the server
    00063          * will be automatically restarted, and another spawn attempt will be made.
    00064          * If restarting the server fails, or if the second spawn attempt fails,
    00065          * then an exception will be thrown.
    00066          *
    00067          * @param options An object containing the details for this spawn operation,
    00068          *                such as which application to spawn. See PoolOptions for details.
    00069          * @return A smart pointer to a Process object, which represents the application
    00070          *         process that has been spawned. Use this object to communicate with the
    00071          *         spawned process.
    00072          * @throws SpawnException Something went wrong.
    00073          * @throws boost::thread_interrupted
    00074          * @throws Anything thrown by options.environmentVariables->getItems().
    00075          */
    00076         virtual ProcessPtr spawn(const PoolOptions &options) = 0;
    00077
    00078         /**
    00079          * Shutdown the ApplicationSpawner server that's running at the given
    00080          * application root. This method should be called when it's time to reload
    00081          * an application.
    00082          *
    00083          * @throws SystemException Unable to communicate with the spawn server,
    00084          *         even after a restart.
    00085          * @throws SpawnException The spawn server died unexpectedly, and a
    00086          *         restart was attempted, but it failed.
    00087          */
    00088         virtual void reload(const string &appRoot) = 0;
    00089
    00090         /**
    00091          * Forcefully kill the spawn server. This AbstractSpawnManager's state will
    00092          * not be modified, so that it won't know that the spawn server is killed
    00093          * until next time it sends a command to it.
    00094          *
    00095          * Used within unit tests.
    00096          */
    00097         virtual void killSpawnServer() const = 0;
    00098
    00099         /**
    00100          * Returns the spawn server's PID. Used within unit tests.
    00101          */
    00102         virtual pid_t getServerPid() const = 0;
    00103 };
    00104
    00105 /** Convenient alias for AbstractSpawnManager smart pointer. */
    00106 typedef shared_ptr<AbstractSpawnManager> AbstractSpawnManagerPtr;
    00107
    00108 } // namespace Passenger
    00109
    00110 #endif /* _PASSENGER_ABSTRACT_SPAWN_MANAGER_H_ */