[master] 4d6ca8c5f doc: A word on VSC_Arg()

Dridi Boukelmoune dridi.boukelmoune at gmail.com
Fri Sep 11 20:05:10 UTC 2020

commit 4d6ca8c5f426a8277add3ca34f5dc1f282177442
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Fri Sep 11 22:02:22 2020 +0200

    doc: A word on VSC_Arg()
    And a quick note on the workspace API plus homework for later.

diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 0f150d59c..29ccd5a5b 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -152,6 +152,9 @@ disruption.
 Changes for developers and VMOD authors
 The workspace API saw a number of changes in anticipation of a future
 inclusion in VRT. The deprecated ``WS_Reserve()`` function was finally
 removed, the functions ``WS_ReserveSize()`` and ``WS_ReserveAll()`` were
@@ -169,10 +172,31 @@ new ``WS_ReservationSize()`` function.
 The return value for ``WS_Printf()`` is now a constant string.
+In general, accessing any field of ``struct ws`` is strongly discouraged
+and if the workspace API doesn't satisfy all your needs please bring
+that to our attention.
 VMOD authors who would like to generate VCC files can now use the
 ``VARNISH_VMODS_GENERATED()`` macro from ``varnish.m4`` for autotools
+There are three new VSC arguments that can be set with the ``VSC_Arg()``
+- ``'I'`` to include counters matching a glob pattern
+- ``'X'`` to exclude counters matching a glob pattern
+- ``'R'`` to include required counters regardless of ``'I'`` and ``'X'``
+The ``'f'`` argument is now deprecated and emulated with ``'I'`` and ``'X'``.
+Filtering with ``'f'`` used to check exclusions first and then inclusions,
+they are all tested in order and the first to match determines the outcome.
+The ``'R'`` argument takes precedence over regular filtering and can be used
+to ensure that some counters are present regardless of user configuration.
 **XXX changes concerning VRT, the public APIs, source code organization,
 builds etc.**
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 9922355b4..27cb67c94 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -61,6 +61,9 @@ After::
+TODO: a word on ``varnishstat -f`` being deprecated and ``-{I,X}`` being
@@ -73,4 +76,9 @@ The new query would be::
     varnishlog -q 'BackendClose[2] ~ www and BackendClose[3] eq recycle'
+TODO: a similar note as ``varnishstat -f`` for ``VSC_Arg('f')``.

More information about the varnish-commit mailing list