Appendix: Spyglass

If you want to know even more about Unix processes then your next stop should be the included Spyglass project. Why? Because it was written specifically to showcase Unix programming concepts.

The case studies you read are meant to showcase the same thing, but at times they can be dense and hard to read when you’re new to Unix programming. Spyglass is meant to bridge that gap.

Spyglass' Architecture#

Spyglass is a web server. It opens a socket to the outside world and handles web requests. Spyglass parses HTTP, is Rack-compliant, and is awesome.

Here’s a brief summary of how to start a Spyglass server and what happens when it receives an HTTP request.

Booting Spyglass#

$ spyglass
$ spyglass -p other_port
$ spyglass -h # for help

Before a Request Arrives#

After it boots, control is passed to Spyglass::Lookout. This class DOES NOT preload the Rack application and knows nothing about HTTP, it just waits for a connection. At this point in time Spyglass is extremely lightweight, it’s nothing more than just an open socket.

Connection is Made#

When Spyglass::Lookout is notified that a connection has been made it forks a Spyglass::Master to actually handle the connection. Spyglass::Lookout uses Process.wait after forking the master process, so it remains idle until the master exits.

Spyglass::Master is responsible for preloading the Rack application and forking/babysitting worker processes. The master process itself doesn’t know anything about HTTP parsing or request handling.

The real work is done in Spyglass::Worker. It accepts connections using the method outlined in the chapter on preforking, leaning on the kernel for load balancing. Once it has a connection it parses the HTTP request, calls the Rack app, and writes the response to the client.

Things Get Quiet#

So long as there is a steady flow of incoming traffic Spyglass continues to act as a preforking server. If its internal timeout is able to expire without receiving any more incoming requests then the master process, and all its worker processes, exit. Control is returned to Spyglass::Lookout and the workflow begins again.

Getting Started#

Spyglass is not a production-ready server, so don’t rush to start using it for your projects! It’s a codebase that’s meant to be read. It’s heavily commented and formatted documentation is generated with rocco.

The best thing to do at this point is enter the code directory that comes with this book in your terminal, find the Spyglass codebase, and run rake read. This will open up the formatted documentation in your browser for your reading pleasure.

Now go forth and read the code! And may the fork(2) be with you!