=============
vmod_dispatch
=============

-------------------------------------------------------------------
Varnish Module for dispatching control to VCL labels or subroutines
-------------------------------------------------------------------

DESCRIPTION
===========

Varnish Module (VMOD) for dispatching control to VCL labels or
subroutines.  Both the ``label`` and ``sub`` objects have an
``.add()`` method used in ``vcl_init``, to assign an integer to a
label or subroutine. The integer can then be used in the
``label.go(INT)`` method to branch to the corresponding label, or in
``sub.call(INT)`` to call the subroutine.

See ``varnish-cli(7)`` and ``vcl(7)`` for details about VCL labels and
subroutines.

Examples::

  # Assign 0 to VCL label mylabel.
  sub vcl_init {
	new labelobj = dispatch.label();
	# The string in .add() must match the label name.
	labelobj.add(0, "mylabel");
  }

  sub vcl_recv {
	if (req.url == "/label0") {
		labelobj.go(0);
	}
  }

  # Assign 1 to VCL subroutine sub1
  sub vcl_init {
	new subobj = dispatch.sub();
	# The string in .add() must match the VCL symbol for the
        # subroutine.
	subobj.add(1, "sub1");
  }

  sub sub1 {
	std.log("VCL subroutine sub1 called");
  }

  sub vcl_recv {
	if (req.url == "/call1") {
		subobj.call(1);
	}
  }

REQUIREMENTS
============

The VMOD requires Varnish since version 6.0.0.

The VMOD is built with strict ABI compatibility, meaning that it MUST
be run against exactly the same version of Varnish against which it
was built -- the version strings must be identical, including the
revision string (the source repository commit ID).

INSTALLATION
============

See `INSTALL.rst <INSTALL.rst>`_ in the source repository.

SEE ALSO
========

* varnishd(1)
* vcl(7)
* varnish-cli(7)
* VMOD source repository: https://code.uplex.de/uplex-varnish/libvmod-dispatch

COPYRIGHT
=========

::

  Copyright (c) 2017-2018 UPLEX Nils Goroll Systemoptimierung
  All rights reserved
 
  Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
 
  See LICENSE