This document provides some technical information about Varnish, about the differnt terms used in Varnish and in its code. For an introduction from the architect on the design and concepts of Varnish, see ArchitectNotes. For more developer resources, see DeveloperResources.

Plugable components

Most of the parts that make up Varnish is pluggable, giving the option of choosing what suits your need best.

Storage

The storage component, or stevedore, is responsible for storing and retrieving data. The available stevedores are

• file: mmap's a file and uses it for storage
• malloc: allocates a chunk of memory
• synth: backend for synthetic content. Only used internally.
• umem: A Solaris specific stevedore.

Acceptors

The name "acceptors" is a bit misleading, as the role is not to accept the TCP connection. Their role is to monitor the socket, polling it to see if there are any more data awaiting after the initial request has been served. A better name would be "TCP nannies". The choices of "nannies" are

• kqueue
• epoll
• poll
• ports

Director

A director is used to group backends together, and then choose a backend based on the algorithm of the director. There is always a director in use; if noen is specified, the backend is wrapped in a 'simple' director. The available directors are

• simple: used internally
• round-robin: chooses backends in a round robin fashion
• random: chooses backends randomly. Each backend is weighted, increasing (or decreasing) the chance of being chosen.

Hash

The 'hash' algorithm,or the lookup algoritm used to retrieve an object (to be more precise). As the simple_list is a linked list, this very slow, it is intended used for debugging purposes, ou'd probably never want anything but the classic algorithm. The available hash algorithms are

• classic: A standard hash table. This is the default. The number of buckets can be tweaked.
• simple-list. A simle doubly linked list.

Acceptor flow and threads

The following chart shows the handling of connections and the various threads involved:

The steps involved when handling a connection are

1. The acceptor tread receives a connection
2. A session object is created for that connection and added to the queue
3. An available worker thread picks up the session object from the queue
4. The worker executes the state machine (see next section)
5. The worker returns a response
6. If the worker receives more data on the connection, the state machine is rerun with the next request

The other maintenance threads are

Herder thread

Handles the thread pools and adds threads if necessary up the defined maximum.

Grim reaper thread

Monitors the TTL of the objects, and removes then when expired..

Acceptor ("TCP nanny") thread

This threads polls the file descriptors of the session object so see if there are any more requests on the connection. The polling mechnanism is configurable (see above).

Varnish state machine

The state machine is the heart of Varnish and where your VCL configuration is executed (for the default VCL, and a similar flow chart, see VCLExampleDefault). The following chart shows the state machine, and the possible flow between the states:

The red labels indicates where a similar vcl_<state> function is executed. The default VCL will be executed if a state function is not defined, or the state function does not return the next state to be executed.

A note should be given for the 'first' and 'start' states; 'first' is only executed for the first request of the session. Subsequent requests in the same session (i.e. TCP connection) starts at the 'start' state.

At the bottom of the C

Varnish is a large and complex application written in C, and looking at the code for the first time can be a daunting experience. This section will hopefully make it a little less so.

Files

After checking checking out the code, you'll have the directories

varnish-cache varnish-doc varnish-logo varnish-tools

Varnish-cache is the directory containing the Varnish source code. Varnish-tools can be usefull as it contains various (not necessarily maintained) plugins.

Inside varnish-cache, the source for the binaries are located in bin/<application>, while the support libraries are found in lib/<library>.

Structures

Varnish has a number of data structures. Unfortunately, the names are not always that verbose and easy to decipher. So here are the important structs and their typical variable names to ease the code reading:

Structure	Typical variable name	Description
struct sess	*sp	The session structure, which holds the TCP connection
struct worker	*wrk	Worker thread handling a requests
struct ws	*ws, *w	The workspace. A private memory area for a sesssion or http request/response
struct obj	*obj, *o	An object, i.e. HTTP document
struct objhead	*oh	Object head. Collection of objects with the same hash. (FIXME: noe med Vary?)
struct http	*h	HTTP request or response with status code, headers, etc. Contians no reference to the object
struct txt	*t	A text structure, with pointers to the beging and end of the text data
struct ban		Regular expression for objects that are to be banned from cache

Acceptor flow revisited

When looking at new code, it is always useful to find a place to start. So here is the acceptor flow, with reference to file and function in the format 'file:function', relative to the directory bin/varnishd:

1. The acceptor thread receives a connection (cache_acceptor.c: vca_acct)
2. A session object is created for that connection and added to the queue (cache_pool.c:WRK_QueueSession)
3. An available worker thread picks up the session object from the queue (cache_pool.c:WRK_Queue()) *
4. The worker executes the state machine (cache_center.c:CNT_Session)
5. The worker returns a response
6. If the worker receives more data on the connection, the state machine is rerun with the next request (cache_center.c:cnt_again()) (cache_acceptor.c:vca_handover())

* WRK_Queue() signals the thread (cahe_pool.c:wrk_thread), which calls the function pointer defined wrk->func. This is set to wrk_do_cnt_sess() by WRK_QueueSession() before calling WRK_Queue().