insd::SocketServ class

The SocketServ class allows for the creation of a Unix domain socket at the server end.

A socket file is created in the server process's run-path, which client instances can then connect to in order to connect to the server process and send/receive data.

Methods

SocketServ()

The constructor takes no parameters. When the SocketServ object is created, a socket is set up (although not yet mapped to a file as necessary for clients to connect to it). If a new socket cannot be allocated, a std::system_error exception is thrown.

~SocketServ()

The destructor closes the socket and deletes the socket file, then waits for all client connection threads to complete before returning.
Note: Each client connection handler should periodically check the status returned by the SocketServ object's active() method, and return as soon as possible if the state becomes false. Otherwise, the SocketServ object's destructor may hang indefinitely waiting for the offending thread to finish.

Note: To avoid potential race conditions and undefined behaviour, the SocketServ object should be created and destroyed within the same thread as is used to run the event loop. This makes sure the SocketServ object has been fully constructed before it is granted control of the thread, and that it has cleanly released control of the thread before it is destroyed.

void mapFile(std::string filename)

Creates a new socket file in the filesystem that is mapped to the socket server object. The file will be deleted automatically when the SocketServ object is destroyed. Any existing file with the same name will be overwritten.

As an example, for a server process named serverd, the socket file might typically be /run/serverd.socket . If a relative path is specified, the file will be created relative to the present-working-directory of the server process (such as /run/), which was specified when the server process was created.

By knowing the path and filename of the socket file, client processes can then connect to the server via the clientConnect function.

void operator()(NewConHandler& ref)

Calling the function operator causes the SocketServ object to take over control of the execution thread. It then runs in an indefinite event loop, which monitors the socket for new connection requests, accepts new connections, and automatically spawns a new thread for each new connection.

ref is a NewConHandler function-object, which is called whenever a new client connection is made.

void stop()

Instructs the SocketServ object to cease accepting new connections and break out of its event loop. (stop() would generally be called from a different thread to the one accepting new connections.)

bool active()

Returns true if the SocketServ object has commenced managing connections, and false once the SocketServ() object has ceased accepting new connections (e.g. after stop() has been called or the process has received a SIGINT or SIGTERM from another process).

Each connection handler thread should periodically check the state returned by active() to see if the sever is still running in a normal state, and return as soon as practical once the state becomes false.