1 /++ 2 socketplate server 3 4 ## Maintainer manual 5 6 If you’re looking forward to work on this library itself (or create your own socket server with it), 7 this documentation will probably be interesting for you. 8 9 $(NOTE 10 If you’re just using socketplate “the regular way”, there won’t be much interesting info here. 11 12 You might like to read through it, when you want to learn more about the technical details of this library. 13 Otherwise feel free to skip the following chapters. 14 ) 15 16 ### Architecture 17 18 The central point of service is the [socketplate.server.server.SocketServer|SocketServer|]. 19 Listeners are registered on it. 20 21 Once all listeners are registered, bind to the listening addresses via [socketplate.server.server.SocketServer.bind|SocketServer.bind]. 22 23 Workers are spawned automatically as needed by [socketplate.server.server.SocketServer.run|SocketServer.run]. 24 This function enables listening on all sockets as well. 25 26 #### Server + main thread 27 28 The server will usually run from the main thead. 29 30 $(TIP 31 If it is supposed run from another thread, 32 either disable signal handler setup (see Tunables) 33 or forward SIGINT and SIGTERM to the server thread (see [socketplate.signal.forwardSignal()]). 34 ) 35 36 After starting the worker threads, the server will join them. 37 It will eventually exit, once all workers have stopped. 38 Unhandled exceptions in any of the workers will be indicated by `SocketServer.run` returning a non-zero status value. 39 Obviously they cannot be rethrown by server as this would probably crash the whole server, 40 despite Exceptions not being meant to signal logic errors. 41 42 If signal handling is enabled, the server will initiate a graceful shutdown on SIGINT and SIGTERM. 43 Those signals get forwarded to worker threads, so that they can gracefully close sockets as well. 44 This is especially relevant for accepted sockets (that execute their connection handlers). 45 46 #### Workers 47 48 Workers are implemented as $(B threads). 49 50 $(SIDEBAR 51 $(B Forking) as alternative to the used $(B threading) approach was taken into consideration. 52 The author came to the conclusion that offering different multi-tasking options 53 would just introduce a lot of complexity to consider (downstream as well). 54 Threading has to advantage to be available cross-platform as opposed to forking 55 that is unavailable on the widely used Win32/Win64. 56 ) 57 58 As socketplate uses blocking IO, individual workers are spawned for each listener. 59 60 Total number of workers = `listeners × tunables.workers` 61 62 The `shutdown` method of workers is used for graceful shutdown of them. 63 64 The [socketplate.server.worker|worker module] relies a lot on `module private` functions. 65 66 #### Listeners 67 68 [socketplate.server.worker.SocketListener|SocketListener|] is a wrapper for the “listening socket” 69 shared across workers. 70 71 `bind` + `listen` are called by the server before starting the workers. 72 73 `accept` is called in the worker’s loop until the worker is shut down. 74 75 `ensureShutdownClosed` 76 is called by the worker before exiting 77 and shuts down and closes the listener’s socket (if still open). 78 79 `shutdownAccepted` 80 shuts down and closes the worker’s (in fact: listener’s) currently accepted connection if applicable. 81 +/ 82 module socketplate.server; 83 84 public import socketplate.server.server; 85 public import socketplate.server.worker;