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:

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.