commit 2a84483ffbfc48f11f28e05c453a29eb0e1f5e81
Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
Date: Fri Mar 15 10:51:35 2024 +0100
whats-new: Add upgrade notes
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..706966391 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -1,33 +1,69 @@
-**Note: This is a working document for a future release, with running
-updates for changes in the development branch. For changes in the
-released versions of Varnish, see:** :ref:`whats-new-index`
-
.. _whatsnew_upgrading_CURRENT:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Upgrading to Varnish **$NEXT_RELEASE**
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-**XXX: how to upgrade from previous deployments to this
-version. Limited to work that has to be done for an upgrade, new
-features are listed in "Changes". Explicitly mention what does *not*
-have to be changed, especially in VCL. May include, but is not limited
-to:**
+Logs
+====
+
+The optional reason field of ``BackendClose`` records changed from a
+description (for example "Receive timeout") to a reason tag (for example
+``RX_TIMEOUT``). This will break VSL queries based on the reason field.
+
+Using a tag should however make queries more reliable::
+
+ # before
+ varnishlog -q 'BackendClose ~ "Receive timeout"'
+
+ # after
+ varnishlog -q 'BackendClose[4] eq RX_TIMEOUT'
+
+Such queries would no longer break when a description is changed.
+
+Timeouts
+========
+
+The value zero for timeouts could mean either timing out immediately, never
+timing out, or not having a value and falling back to another. The semantic
+changed so zero always means non-blocking, timing out either immediately after
+checking whether progress is possible, or after a millisecond in parts where
+this can't practically be done in a non-blocking fashion.
+
+In order to disable a timeout, that is to say never time out, the value
+``INFINITY`` is used (or tested with ``isinf()``).
+
+In the places where a timeout setting may fall back to another value, like
+VCL variables falling back to parameters, ``NAN`` is used to convey the lack
+of timeout setting.
+
+VCL
+~~~
+
+All the timeouts backed by parameters can now be unset, meaning that setting
+the value zero no longer falls back to parameters.
+
+Parameters
+~~~~~~~~~~
-* Elements of VCL that have been removed or are deprecated, or whose
- semantics have changed.
+All the timeout parameters that can be disabled are now documented with the
+``timeout`` flag, meaning that they can take the special value ``never`` for
+that purpose::
-* -p parameters that have been removed or are deprecated, or whose
- semantics have changed.
+ varnishadm param.set pipe_timeout never
-* Changes in the CLI.
+VRT
+~~~
-* Changes in the output or interpretation of stats or the log, including
- changes affecting varnishncsa/-hist/-top.
+For VMOD authors, it means that the ``vtim_dur`` type expects ``INFINITY`` to
+never time out or ``NAN`` to not set a timeout.
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+For VMOD authors managing backends, there is one exception where a timeout
+fallback did not change from zero to ``NAN`` in ``struct vrt_backend``. The
+``vtim_dur`` fields must take a negative value in order to fall back to the
+respective parameters due to a limitation in how VCL is compiled.
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
- clients.
+As a convenience, a new macro ``VRT_BACKEND_INIT()`` behaves like ``INIT_OBJ``
+but initializes timeouts to a negative value.
*eof*
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit
Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
Date: Fri Mar 15 10:51:35 2024 +0100
whats-new: Add upgrade notes
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 6143fde99..706966391 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -1,33 +1,69 @@
-**Note: This is a working document for a future release, with running
-updates for changes in the development branch. For changes in the
-released versions of Varnish, see:** :ref:`whats-new-index`
-
.. _whatsnew_upgrading_CURRENT:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Upgrading to Varnish **$NEXT_RELEASE**
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-**XXX: how to upgrade from previous deployments to this
-version. Limited to work that has to be done for an upgrade, new
-features are listed in "Changes". Explicitly mention what does *not*
-have to be changed, especially in VCL. May include, but is not limited
-to:**
+Logs
+====
+
+The optional reason field of ``BackendClose`` records changed from a
+description (for example "Receive timeout") to a reason tag (for example
+``RX_TIMEOUT``). This will break VSL queries based on the reason field.
+
+Using a tag should however make queries more reliable::
+
+ # before
+ varnishlog -q 'BackendClose ~ "Receive timeout"'
+
+ # after
+ varnishlog -q 'BackendClose[4] eq RX_TIMEOUT'
+
+Such queries would no longer break when a description is changed.
+
+Timeouts
+========
+
+The value zero for timeouts could mean either timing out immediately, never
+timing out, or not having a value and falling back to another. The semantic
+changed so zero always means non-blocking, timing out either immediately after
+checking whether progress is possible, or after a millisecond in parts where
+this can't practically be done in a non-blocking fashion.
+
+In order to disable a timeout, that is to say never time out, the value
+``INFINITY`` is used (or tested with ``isinf()``).
+
+In the places where a timeout setting may fall back to another value, like
+VCL variables falling back to parameters, ``NAN`` is used to convey the lack
+of timeout setting.
+
+VCL
+~~~
+
+All the timeouts backed by parameters can now be unset, meaning that setting
+the value zero no longer falls back to parameters.
+
+Parameters
+~~~~~~~~~~
-* Elements of VCL that have been removed or are deprecated, or whose
- semantics have changed.
+All the timeout parameters that can be disabled are now documented with the
+``timeout`` flag, meaning that they can take the special value ``never`` for
+that purpose::
-* -p parameters that have been removed or are deprecated, or whose
- semantics have changed.
+ varnishadm param.set pipe_timeout never
-* Changes in the CLI.
+VRT
+~~~
-* Changes in the output or interpretation of stats or the log, including
- changes affecting varnishncsa/-hist/-top.
+For VMOD authors, it means that the ``vtim_dur`` type expects ``INFINITY`` to
+never time out or ``NAN`` to not set a timeout.
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+For VMOD authors managing backends, there is one exception where a timeout
+fallback did not change from zero to ``NAN`` in ``struct vrt_backend``. The
+``vtim_dur`` fields must take a negative value in order to fall back to the
+respective parameters due to a limitation in how VCL is compiled.
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
- clients.
+As a convenience, a new macro ``VRT_BACKEND_INIT()`` behaves like ``INIT_OBJ``
+but initializes timeouts to a negative value.
*eof*
_______________________________________________
varnish-commit mailing list
varnish-commit@varnish-cache.org
https://www.varnish-cache.org/lists/mailman/listinfo/varnish-commit