...
 
Commits (3)
......@@ -95,8 +95,9 @@ below).
Since the update checks run in the background, the file I/O that the
checks require is not incurred during any request/response
transaction. The I/O effort to read the contents may also happen in
the background, or during the first access after the file has changed;
that too is platform-dependent (see below).
the background, or during the first access after initialization, or
after the file has changed; that too is platform-dependent (see
below).
.. _vcl.state: https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-state-configname-auto-cold-warm
......@@ -202,8 +203,8 @@ If ``log_checks`` is ``true`` (default ``false``), then the activity
of update checks is logged in the Varnish log using the tag ``Debug``
(see `vsl(7)`_). By default, ``Debug`` logs are filtered from the
Varnish log; to see them, add ``Debug`` to the varnishd parameter
|vsl_mask|_, for example by invoking varnishd with ``-p
vsl_mask=+Debug``. Since update checks do not happen during any
|vsl_mask|_, for example by invoking varnishd with
``-p vsl_mask=+Debug``. Since update checks do not happen during any
request/response transaction, they are logged with pseudo-XID 0, and
are only visible when the log is read with `raw grouping`_, for
example by invoking `varnishlog(1)`_ with ``-g raw``.
......@@ -212,18 +213,47 @@ Regardless of the value of ``log_checks``, errors encountered during
update checks are logged with the tag ``Error``, also with XID 0 (and
hence visible in raw grouping).
Examples::
sub vcl_init {
# A reader for the file at the absolute path, using default
# ttl=120s.
new foo = file.reader("/path/to/foo");
# A reader for the file on the default search path, with
# update checks every five minutes.
new synth_body = file.reader("synth_body.html", ttl=300s);
# A reader for the file on the given search path, with
# default TTL, and logging for update checks.
new bar = file.reader("bar", path="/var/run/d1:/var/run/d2",
log_checks=true);
# A reader for the file with no update checks.
new baz = file.reader("baz", ttl=0s);
}
.. _xreader.get():
STRING xreader.get()
--------------------
Retrieves the contents of file specified in the constructor. If the
``ttl`` has elapsed, then ``.get()`` checks if the file has changed;
if so, the new contents of the file are read, cached and returned. If
the ``ttl`` has not elapsed, or if the file is unchanged, then the
cached contents are returned.
Return the contents of the file specified in the constructor, as
currently cached. If the most recent update check encountered an
error, then VCL failure is invoked (see `ERRORS`_).
XXX ...
Example::
sub vcl_deliver {
set resp.http.Foo = foo.get();
}
Take care if you use ``.get()`` to set a header, as in the example,
that the file contents do *not* end in a newline. If so, then the
newline appears after the header contents, resulting in an empty line
after the header. Since an empty line separates the headers from the
body in an HTTP message, this is very likely to result in an invalid
message.
.. _xreader.synth():
......@@ -240,7 +270,7 @@ XXX ...
BOOL xreader.error()
--------------------
Returns true if and only if an error condition was determined the last
Return true if and only if an error condition was determined the last
time the file was checked.
XXX ...
......@@ -250,7 +280,7 @@ XXX ...
STRING xreader.errmsg()
-----------------------
Returns the error message for any error condition determined the last
Return the error message for any error condition determined the last
time the file was checked, or a message indicating that there was no
error.
......@@ -261,7 +291,7 @@ XXX ...
BYTES xreader.size()
--------------------
Returns the size of the file when it was most recently checked.
Return the size of the file when it was most recently checked.
XXX ...
......@@ -270,7 +300,7 @@ XXX ...
TIME xreader.mtime()
--------------------
Returns the modification time of the file determined when it was mostly
Return the modification time of the file determined when it was mostly
recently checked.
XXX ...
......@@ -280,7 +310,7 @@ XXX ...
DURATION xreader.next_check()
-----------------------------
Returns the time remaining until the next check will be performed.
Return the time remaining until the next check will be performed.
XXX ...
......
......@@ -91,8 +91,9 @@ below).
Since the update checks run in the background, the file I/O that the
checks require is not incurred during any request/response
transaction. The I/O effort to read the contents may also happen in
the background, or during the first access after the file has changed;
that too is platform-dependent (see below).
the background, or during the first access after initialization, or
after the file has changed; that too is platform-dependent (see
below).
.. _vcl.state: https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-state-configname-auto-cold-warm
......@@ -188,8 +189,8 @@ If ``log_checks`` is ``true`` (default ``false``), then the activity
of update checks is logged in the Varnish log using the tag ``Debug``
(see `vsl(7)`_). By default, ``Debug`` logs are filtered from the
Varnish log; to see them, add ``Debug`` to the varnishd parameter
|vsl_mask|_, for example by invoking varnishd with ``-p
vsl_mask=+Debug``. Since update checks do not happen during any
|vsl_mask|_, for example by invoking varnishd with
``-p vsl_mask=+Debug``. Since update checks do not happen during any
request/response transaction, they are logged with pseudo-XID 0, and
are only visible when the log is read with `raw grouping`_, for
example by invoking `varnishlog(1)`_ with ``-g raw``.
......@@ -198,15 +199,44 @@ Regardless of the value of ``log_checks``, errors encountered during
update checks are logged with the tag ``Error``, also with XID 0 (and
hence visible in raw grouping).
Examples::
sub vcl_init {
# A reader for the file at the absolute path, using default
# ttl=120s.
new foo = file.reader("/path/to/foo");
# A reader for the file on the default search path, with
# update checks every five minutes.
new synth_body = file.reader("synth_body.html", ttl=300s);
# A reader for the file on the given search path, with
# default TTL, and logging for update checks.
new bar = file.reader("bar", path="/var/run/d1:/var/run/d2",
log_checks=true);
# A reader for the file with no update checks.
new baz = file.reader("baz", ttl=0s);
}
$Method STRING .get()
Retrieves the contents of file specified in the constructor. If the
``ttl`` has elapsed, then ``.get()`` checks if the file has changed;
if so, the new contents of the file are read, cached and returned. If
the ``ttl`` has not elapsed, or if the file is unchanged, then the
cached contents are returned.
Return the contents of the file specified in the constructor, as
currently cached. If the most recent update check encountered an
error, then VCL failure is invoked (see `ERRORS`_).
XXX ...
Example::
sub vcl_deliver {
set resp.http.Foo = foo.get();
}
Take care if you use ``.get()`` to set a header, as in the example,
that the file contents do *not* end in a newline. If so, then the
newline appears after the header contents, resulting in an empty line
after the header. Since an empty line separates the headers from the
body in an HTTP message, this is very likely to result in an invalid
message.
$Method VOID .synth()
......@@ -217,14 +247,14 @@ XXX ...
$Method BOOL .error()
Returns true if and only if an error condition was determined the last
Return true if and only if an error condition was determined the last
time the file was checked.
XXX ...
$Method STRING .errmsg()
Returns the error message for any error condition determined the last
Return the error message for any error condition determined the last
time the file was checked, or a message indicating that there was no
error.
......@@ -232,20 +262,20 @@ XXX ...
$Method BYTES .size()
Returns the size of the file when it was most recently checked.
Return the size of the file when it was most recently checked.
XXX ...
$Method TIME .mtime()
Returns the modification time of the file determined when it was mostly
Return the modification time of the file determined when it was mostly
recently checked.
XXX ...
$Method DURATION .next_check()
Returns the time remaining until the next check will be performed.
Return the time remaining until the next check will be performed.
XXX ...
......