Skip to content
Permalink
Browse files

name vmod function / constructor / method RST xref like VCL

as @slimhazard pointed out when reviewing a suggestion I made to some
vmod documentation, the vmodtool generated link target names are
confusing to users: vmod_foo.func is nothing you can use as VCL, while
foo.func() is.
  • Loading branch information...
nigoroll authored and bsdphk committed Sep 9, 2019
1 parent 06ffea8 commit 904ceabf07c294983efcebfe1d614c2d2fd5cdda
@@ -162,7 +162,7 @@ Health Probes
=============

It is possible in a VCL program to query the health of a director (see
:ref:`vmod_std.healthy`). A director can report its health if it implements the
:ref:`std.healthy()`). A director can report its health if it implements the
``healthy`` function, it is otherwise always considered healthy.

Unless you are making a dynamic backend, you need to take care of the
@@ -117,7 +117,7 @@ to make them more flexible and easier to use. The ``std.``\ *x2y*
conversion functions are now deprecated. See
:ref:`whatsnew_upgrading_std_conversion_2019_03`.

The function :ref:`vmod_directors.lookup` has been added to
The function :ref:`directors.lookup()` has been added to
:ref:`vmod_directors(3)`, only for use in ``vcl_init`` or
``vcl_fini``.

@@ -197,7 +197,7 @@ vcl_recv

* Added ``req.storage``, which tells Varnish which storage backend to
use if you choose to save the request body (see
:ref:`vmod_std.cache_req_body`).
:ref:`std.cache_req_body()`).

* ``return(vcl(LABEL))`` may not be called after a restart. It can
only be called from the active VCL instance.
@@ -232,9 +232,9 @@ nuke limit is used in all cases.
vmod_std
~~~~~~~~

* Added ``std.getenv()``, see :ref:`vmod_std.getenv`.
* Added :ref:`std.getenv()`.

* Added ``std.late_100_continue()``, see :ref:`vmod_std.late_100_continue`.
* Added :ref:`std.late_100_continue()`.

Other changes
=============
@@ -121,7 +121,7 @@ situation.
vmod_std
~~~~~~~~

Added :ref:`vmod_std.file_exists`.
Added :ref:`std.file_exists()`.

New VMODs in the standard distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -461,9 +461,9 @@ backend, or set a value for the Host header in VCL.
VMOD std
--------

:ref:`std.port(IP) <vmod_std.port>` always returns 0 when applied to a
:ref:`std.port()` always returns 0 when applied to a
``*.ip`` variable whose value is set to ``0.0.0.0`` because the
listener is UDS. :ref:`std.set_ip_tos(INT) <vmod_std.set_ip_tos>` is
listener is UDS. :ref:`std.set_ip_tos()` is
silently ignored when the listener is UDS.

The ``shard`` director
@@ -519,7 +519,7 @@ except for ``req.restarts`` and ``req.xid``, which change by design.

If you need to reset the client request headers to their original
state (before changes in VCL), call
:ref:`std.rollback(req) <vmod_std.rollback>`.
:ref:`std.rollback()`.

``return(restart)`` can now be called from ``vcl_recv{}``.

@@ -138,7 +138,7 @@ Other changes to VCL
VMODs
=====

Added the :ref:`vmod_std.fnmatch` function to :ref:`vmod_std(3)`, which
Added the :ref:`std.fnmatch()` function to :ref:`vmod_std(3)`, which
you can use for shell-style wildcard matching. Wildcard patterns may
be a good fit for matching URLs, to match against a pattern like
``/foo/*/bar/*``. The patterns can be built at runtime, if you need to
@@ -58,11 +58,11 @@ The existing type-conversion functions in :ref:`vmod_std(3)` have been
reworked to make them more flexible and easier to use. These functions
now also accept suitable numeral or quantitative arguments.

* :ref:`vmod_std.duration`
* :ref:`vmod_std.bytes`
* :ref:`vmod_std.integer`
* :ref:`vmod_std.real`
* :ref:`vmod_std.time`
* :ref:`std.duration()`
* :ref:`std.bytes()`
* :ref:`std.integer()`
* :ref:`std.real()`
* :ref:`std.time()`

These type-conversion functions should be fully backwards compatible,
but the following differences should be noted:
@@ -76,15 +76,15 @@ but the following differences should be noted:
* Conversion functions now only ever truncate if necessary (instead of
rounding).

* :ref:`vmod_std.round` has been added for explicit rounding.
* :ref:`std.round()` has been added for explicit rounding.

The following functions are deprecated and should be replaced by the
new conversion functions:

* :ref:`vmod_std.real2integer`
* :ref:`vmod_std.real2time`
* :ref:`vmod_std.time2integer`
* :ref:`vmod_std.time2real`
* :ref:`std.real2integer()`
* :ref:`std.real2time()`
* :ref:`std.time2integer()`
* :ref:`std.time2real()`

They will be removed in a future version of Varnish.

@@ -715,7 +715,7 @@ class FunctionStanza(Stanza):

def parse(self):
self.proto = ProtoType(self)
self.rstlbl = 'vmod_%s.%s' % (self.vcc.modname, self.proto.name)
self.rstlbl = '%s.%s()' % (self.vcc.modname, self.proto.name)
self.vcc.contents.append(self)

def cstuff(self, fo, where):
@@ -748,7 +748,7 @@ def parse(self):
self.fini.argstruct = False
self.fini.args = []

self.rstlbl = 'vmod_%s.%s' % (self.vcc.modname, self.proto.name)
self.rstlbl = '%s.%s()' % (self.vcc.modname, self.proto.name)
self.vcc.contents.append(self)
self.methods = []

@@ -831,7 +831,7 @@ def parse(self):
err("$Method %s: Method names need to start with . (dot)"
% self.proto.bname, warn=False)
self.proto.obj = "x" + self.pfx
self.rstlbl = 'vmod_%s.%s' % ( self.vcc.modname, self.proto.name)
self.rstlbl = 'x%s()' % self.proto.name
p.methods.append(self)

def cstruct(self, fo, define):
@@ -240,7 +240,7 @@ the encoding of the resulting blob according to the scheme
*encoding*. *case* determines the case of hex digits for the
``HEX`` and ``URL`` encodings, and is ignored for other encodings.

As with `vmod_blob.decode`_: If *length* > 0, only decode the first
As with `blob.decode()`_: If *length* > 0, only decode the first
*length* characters of the encoded string, otherwise decode the
entire string. The default value of *length* is 0.

@@ -274,18 +274,18 @@ object, i.e. they specify exactly the same region of memory, or both
are empty.

If the BLOBs are both empty (length is 0 and/or the internal pointer
is ``NULL``), then `vmod_blob.same`_ returns ``true``. If any
non-empty BLOB is compared to an empty BLOB, then `vmod_blob.same`_
is ``NULL``), then `blob.same()`_ returns ``true``. If any
non-empty BLOB is compared to an empty BLOB, then `blob.same()`_
returns ``false``.

$Function BOOL equal(BLOB, BLOB)

Returns true if and only if the two BLOB arguments have equal contents
(possibly in different memory regions).

As with `vmod_blob.same`_: If the BLOBs are both empty, then `vmod_blob.equal`_
As with `blob.same()`_: If the BLOBs are both empty, then `blob.equal()`_
returns ``true``. If any non-empty BLOB is compared to an empty BLOB,
then `vmod_blob.equal`_ returns ``false``.
then `blob.equal()`_ returns ``false``.

$Function INT length(BLOB)

@@ -297,7 +297,7 @@ Returns a new BLOB formed from *length* bytes of the BLOB argument
starting at *offset* bytes from the start of its memory region. The
default value of *offset* is ``0B``.

`vmod_blob.sub`_ fails and returns NULL if the BLOB argument is empty, or if
`blob.sub()`_ fails and returns NULL if the BLOB argument is empty, or if
``offset + length`` requires more bytes than are available in the
BLOB.

@@ -350,28 +350,28 @@ Example::
# blob as base64
set resp.http.The-Blob-b64 = theblob1.encode(BASE64);

For any `vmod_blob.blob`_ object, `encoding` and `case`, encodings via
the `vmod_blob.blob.encode`_ method and the `vmod_blob.encode`_
For any `blob.blob()`_ object, `encoding` and `case`, encodings via
the `xblob.encode()`_ method and the `blob.encode()`_
function are equal::

# Always true:
blob.encode(ENC, CASE, blob.get()) == blob.encode(ENC, CASE)

But the `vmod_blob.blob.encode`_ object method is more efficient --
But the `xblob.encode()`_ object method is more efficient --
the encoding is computed once and cached (with allocation in heap
memory), and the cached encoding is retrieved on every subsequent
call. The `vmod_blob.encode`_ function computes the encoding on every
call. The `blob.encode()`_ function computes the encoding on every
call, allocating space for the string in Varnish workspaces.

So if the data in a BLOB are fixed at VCL initialization time, so that
its encodings will always be the same, it is better to create a
`vmod_blob.blob`_ object. The VMOD's functions should be used for data that are
`blob.blob()`_ object. The VMOD's functions should be used for data that are
not known until runtime.

ERRORS
======

The encoders, decoders and `vmod_blob.sub`_ may fail if there is
The encoders, decoders and `blob.sub()`_ may fail if there is
insufficient space to create the new blob or string. Decoders may also
fail if the encoded string is an illegal format for the decoding
scheme. Encoders will fail for the ``IDENTITY`` and ``BASE64*``
@@ -381,7 +381,7 @@ If any of the VMOD's methods, functions or constructor fail, then VCL
failure is invoked, just as if ``return(fail)`` had been called in the
VCL source. This means that:

* If the ``vmod_blob.blob`_ object constructor fails, or if any methods or
* If the ``blob.blob()`_ object constructor fails, or if any methods or
functions fail during ``vcl_init{}``, then the VCL program will fail
to load, and the VCC compiler will emit an error message.

@@ -399,18 +399,18 @@ LIMITATIONS
===========

The VMOD allocates memory in various ways for new blobs and
strings. The `vmod_blob.blob`_ object and its methods allocate memory
strings. The `blob.blob()`_ object and its methods allocate memory
from the heap, and hence they are only limited by available virtual
memory.

The `vmod_blob.encode`_, `vmod_blob.decode`_ and
`vmod_blob.transcode`_ functions allocate Varnish workspace, as does
`vmod_blob.sub`_ for the newly created BLOB. If these functions are
The `blob.encode()`_, `blob.decode()`_ and
`blob.transcode()`_ functions allocate Varnish workspace, as does
`blob.sub()`_ for the newly created BLOB. If these functions are
failing, as indicated by "out of space" messages in the Varnish log
(with the ``VCL_Error`` tag), then you will need to increase the
varnishd parameters ``workspace_client`` and/or ``workspace_backend``.

The `vmod_blob.transcode`_ function also allocates space on the stack
The `blob.transcode()`_ function also allocates space on the stack
for a temporary BLOB. If this function causes stack overflow, you may
need to increase the varnishd parameter ``thread_pool_stack``.

0 comments on commit 904ceab

Please sign in to comment.
You can’t perform that action at this time.