[master] 419d15f Add missing returns, and do a bit of cleanup
Andreas Plesner
apj at mutt.dk
Fri May 16 17:53:36 CEST 2014
commit 419d15fadd06470ce46c7e4c9883469ba7f748eb
Author: Andreas Plesner <apj at mutt.dk>
Date: Fri May 16 17:53:15 2014 +0200
Add missing returns, and do a bit of cleanup
diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
index 0a90a34..cb6396e 100644
--- a/doc/sphinx/users-guide/vcl-built-in-subs.rst
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -22,8 +22,8 @@ yourself doing frequently.
The `vcl_recv` subroutine may terminate with calling ``return()`` on one
of the following keywords:
- synth
- Return a synthetic object with the specified error code to the
+ synth(status code, reason)
+ Return a synthetic object with the specified status code to the
client and abandon the request.
pass
@@ -52,8 +52,8 @@ shuffling bytes back and forth.
The `vcl_pipe` subroutine may terminate with calling ``return()`` with one
of the following keywords:
- synth(error code, reason)
- Return the specified error code to the client and abandon the request.
+ synth(status code, reason)
+ Return the specified status code to the client and abandon the request.
pipe
Proceed with pipe mode.
@@ -69,8 +69,8 @@ submitted over the same client connection are handled normally.
The `vcl_pass` subroutine may terminate with calling ``return()`` with one
of the following keywords:
- synth(error code, reason)
- Return the specified error code to the client and abandon the request.
+ synth(status code, reason)
+ Return the specified status code to the client and abandon the request.
pass
Proceed with pass mode.
@@ -86,7 +86,7 @@ vcl_hit
Called when a cache lookup is successful.
-.. XXX: missing the "The `vcl_hit` subroutine may terminate with calling ``return()`` with one of the following keywords:" thing. benc
+The `vcl_hit` subroutine may terminate with calling ``return()`` with one of the following keywords:
restart
@@ -97,8 +97,8 @@ Called when a cache lookup is successful.
deliver
Deliver the object. Control passes to `vcl_deliver`.
- synth(error code, reason)
- Return the specified error code to the client and abandon the request.
+ synth(status code, reason)
+ Return the specified status code to the client and abandon the request.
vcl_miss
@@ -111,8 +111,8 @@ retrieve the document from the backend, and which backend to use.
The `vcl_miss` subroutine may terminate with calling ``return()`` with one
of the following keywords:
- synth(error code, reason)
- Return the specified error code to the client and abandon the request.
+ synth(status code, reason)
+ Return the specified status code to the client and abandon the request.
pass
Switch to pass mode. Control will eventually pass to `vcl_pass`.
@@ -121,38 +121,51 @@ of the following keywords:
Retrieve the requested object from the backend. Control will
eventually pass to `vcl_backend_fetch`.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* Varnish emits a guru meditation
+ error.
+
+
vcl_hash
~~~~~~~~
Called after `vcl_recv` to create a hash value for the request. This is
used as a key to look up the object in Varnish.
+The `vcl_hash` subroutine may terminate with calling ``return()`` with one
+of the following keywords:
+
lookup
Look up the object in cache. Control passes to vcl_miss, vcl_hit
or vcl_purge.
-
-
vcl_purge
~~~~~~~~~
Called after the purge has been executed and all its variants have been evited.
+The `vcl_purge` subroutine may terminate with calling ``return()`` with one
+of the following keywords:
+
synth
Produce a response.
+ restart
+ Restart the transaction. Increases the restart counter. If the number
+ of restarts is higher than *max_restarts* Varnish emits a guru meditation
+ error.
+
vcl_deliver
~~~~~~~~~~~
Called before a cached object is delivered to the client.
-The ``vcl_deliver`` subroutine may terminate calling ``return()`` with one
+The `vcl_deliver` subroutine may terminate with calling ``return()`` with one
of the following keywords:
-.. XXX: Should perhaps be return as above? benc
-
deliver
Deliver the object to the client.
@@ -168,7 +181,8 @@ vcl_backend_fetch
Called before sending the backend request. In this subroutine you
typically alter the request before it gets to the backend.
-.. XXX: Missing terminate..keywords sentence? benc
+The `vcl_backend_fetch` subroutine may terminate with calling
+``return()`` with one of the following keywords:
fetch
Fetch the object from the backend.
@@ -180,71 +194,40 @@ typically alter the request before it gets to the backend.
vcl_backend_response
~~~~~~~~~~~~~~~~~~~~
-Called after a response has been successfully retrieved from the
-backend. The response is available as `beresp`.
-
-.. XXX: beresp comes out of the blue here. maybe a short description? benc
-
-Note that Varnish might
-not be talking to an actual client, so operations that require a
-client to be present are not allowed. Specifically there is no `req
-object` and restarts are not allowed.
+Called after the response headers has been successfully retrieved from
+the backend.
-.. XXX: I do not follow sentence above. benc
-
-The `vcl_backend_response` subroutine may terminate with calling ``return()`` with one
-of the following keywords:
+The `vcl_backend_response` subroutine may terminate with calling
+``return()`` with one of the following keywords:
deliver
Possibly insert the object into the cache, then deliver it to the
Control will eventually pass to `vcl_deliver`. Caching is dependant
on 'beresp.cacheable'.
-.. XXX:A parameter? that is set how? benc
-
-
- error(error code, reason)
- Return the specified error code to the client and abandon the request.
+ abandon
+ Abandon the backend request and generates an error.
retry
- Retry the backend transaction. Increases the `retries` counter. If the number
- of retries is higher than *max_retries* Varnish emits a guru meditation
- error.
+ Retry the backend transaction. Increases the `retries` counter.
+ If the number of retries is higher than *max_retries* Varnish
+ emits a guru meditation error.
vcl_backend_error
~~~~~~~~~~~~~~~~~
This subroutine is called if we fail the backend fetch.
-.. XXX:Missing the terminate return structure? benc
+The `vcl_backend_error` subroutine may terminate with calling ``return()``
+with one of the following keywords:
deliver
Deliver the error.
retry
- Retry the backend transaction. Increases the `retries` counter. If the number
- of retries is higher than *max_retries* Varnish emits a guru meditation
- error.
-
-
-vcl_backend_error
-~~~~~~~~~~~~~~~~~
-
-.. XXX: Same name as section above? benc
-
-Called when we hit an error, either explicitly or implicitly due to
-backend or internal errors.
-
-The `vcl_backend_error` subroutine may terminate by calling ``return()`` with one of
-the following keywords:
-
- deliver
- Deliver the error object to the client.
-
- retry
- Retry the backend transaction. Increases the retries counter. If the number
- of retries is higher than *max_retries* Varnish emits a guru meditation
- error.
+ Retry the backend transaction. Increases the `retries` counter. If
+ the number of retries is higher than *max_retries* Varnish emits a
+ guru meditation error.
vcl_init
@@ -253,9 +236,8 @@ vcl_init
Called when VCL is loaded, before any requests pass through it.
Typically used to initialize VMODs.
-.. XXX: Missing the terminate return structure? benc
-
- ``return()`` values:
+The `vcl_init` subroutine may terminate with calling ``return()``
+with one of the following keywords:
ok
Normal return, VCL continues loading.
@@ -267,13 +249,8 @@ vcl_fini
Called when VCL is discarded only after all requests have exited the VCL.
Typically used to clean up VMODs.
-
-.. XXX: Missing the terminate return structure? benc
-
- ``return()`` values:
+The `vcl_fini` subroutine may terminate with calling ``return()``
+with one of the following keywords:
ok
Normal return, VCL will be discarded.
-
-
-.. XXX: Maybe end here with the detailed flowchart from the book together with a reference to the book? benc
More information about the varnish-commit
mailing list