insd::ServerInstance class
An instance of the ServerInstance class refers to an instance of your server process, which may or may not be running at the moment. It provides the following functionality:
Spawn a new server process from scratch if it is not already running.
Check if an existing server process is running.
Request (or force) an existing server process to terminate.
When a server process is created by insd, a corresponding pid-file is also created.
A ServerInstance object uses the presense of a pid-file in a specified location to uniquely
identify a running server process.
Constructor: ServerInstance(std::string runPath, std::string processName)
runPath is the pathname in which your process will store its pidfile, logfile (if enabled)
and socket file (if used). For most Linux systems, this should be /run/.
processName is the name of the server process: usually the name of the binary file used to
execute your server process. By convention, such filenames usually end in d if they correspond
to server processes.
The runPath and processName together uniquely identify a single valid instance
of your server process, and if you are starting are spawning a new server process, a pidfile (text file
containing a Unix Process ID), will be created with the filename processName.pid
within runPath.
If you require multiple instances of your server process on the same machine, you will
have to get creative and provide a different runPath for each.
For example, if your server is called bookshelfd and you require one instance
per user, you might use /run/bookshelfd/username/ for each user's
instance.
The advantage of storing instance files in /run/ as opposed to the
user's home directory is that /run/ is typically mounted as a RAM filesystem
and is erased when the system goes down. This avoids some of the hassle of 'zombie' files
from past instances that didn't terminate properly.
run(insd::ServerMain& sMain, bool makeLog)
Runs a new instance of the server process. The new process will inherit a copy of all the caller's
global variables, and will execute code defined by an object sMain of a class derived
from the insd::ServerMain abstract class.
If makeLog is true, the standard error stream will be redirected to a file
named processName.log which will be created in runPath, where
runPath and processName were defined in the ServerInstance constructor.
If a conflicting pidfile already exists, the function throws an insd::LockFileExists exception
and does not spawn a new instance. This means an instance of the server process may already be running.
isRunning()
Returns nonzero if an instance seems to already be running. This is evident from the existence of a
pidfile, although it may produce a false positive if a server instance terminated abnormally
and the pidfile was not cleaned up.
The value returned is the PID (Process ID) of the already-running process, or zero if there
is no existing instance.
stop(int timeout)
Sends a SIGTERM signal to an existing server instance, then waits for a maximum of timeout
seconds for the process to terminate, and returns true if the server instance has terminated
or false if the timeout has expired.
If timeout is zero, the function returns immediately. It does not wait to see if the server process has
terminated; it simply returns false. The user can then call isRunning() later to check if the
server process has terminated or not.
Throws a insd::NotRunningException if there is no pidfile present.
destroy()
Sends a SIGKILL to the server process to terminate it immediately, then deletes the pidfile.
Throws a insd::NotRunningException if there is no pidfile present.