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.