vmod: Add vmod_math

This adds the following functions:

- math.approx() implementing a notion of "approximately equal" as per the
  reference in the documentation and source code

- math.strfromd() for REAL string formatting without the limitations of the
  built-in formatter. The main motivation for adding this function at this point
  is to make the added test case transparent.

- math.constant() to access REAL constants from math.h and float.h like
  DBL_EPSILON or M_PI.

- math.fpclass() to access INT constants from math.h to compare the return value
  of math.fpclassify() against.

- functions for all math.h functions and function-like macros like sqrt(), exp()
  or log().

This uses a python code generator vmod_math_gen.py to extract most of the
definitions from the opengroup specification for all the math.h functions and
function-like macros and to generate math.constant() and math.fpclass().

The specification document vmod_math_spec.html is deliberately checked in and
added to the distribution to avoid curl running for a normal build. As with
other generated code, the generated files vmod_math.c and vmod_math.vcc are also
added to the dist, but not to git in order to update them for developer builds
based on potential changes to vmod_math_gen.py, but to not run the generator for
builds from a distribution.

Author: nigoroll

.gitignore

@@ -81,6 +81,8 @@ cscope.*out
 /vmod/vcc_*_if.h
 /vmod/vmod_*.rst
 /vmod/vmod_vcs_version.txt
+/vmod/vmod_math.vcc
+/vmod/vmod_math.c
 
 # Man-files and binaries
 /man/*.1

doc/changes.rst

@@ -41,6 +41,8 @@ Vinyl-Cache NEXT (2026-03-15)
 .. PLEASE keep this roughly in commit order as shown by git-log / tig
    (new to old)
 
+* Added vmod ``math``.
+
 .. _4389: https://github.com/varnishcache/varnish-cache/issues/4389
 
 * ``req.ttl`` has been renamed to ``req.max_age`` for clarity, with ``req.ttl``

doc/sphinx/Makefile.am

@@ -206,6 +206,10 @@ include/vmod_proxy.generated.rst: $(top_builddir)/vmod/vmod_proxy.rst
 	cp $(top_builddir)/vmod/vmod_proxy.rst $@
 BUILT_SOURCES += include/vmod_proxy.generated.rst
 
+include/vmod_math.generated.rst: $(top_builddir)/vmod/vmod_math.rst
+	cp $(top_builddir)/vmod/vmod_math.rst $@
+BUILT_SOURCES += include/vmod_math.generated.rst
+
 EXTRA_DIST += $(BUILT_SOURCES)
 CLEANFILES = $(BUILT_SOURCES)
 

doc/sphinx/reference/index.rst

@@ -37,6 +37,7 @@ Bundled VMODs
 	vmod_cookie.rst
 	vmod_directors.rst
 	vmod_h2.rst
+	vmod_math.rst
 	vmod_proxy.rst
 	vmod_purge.rst
 	vmod_std.rst

doc/sphinx/reference/vmod_math.rst

@@ -0,0 +1,7 @@
+..
+	Copyright (c) 2019 Varnish Software AS
+	SPDX-License-Identifier: BSD-2-Clause
+	See LICENSE file for full text of license
+
+
+.. include::	../include/vmod_math.generated.rst

man/Makefile.am

@@ -27,7 +27,8 @@ dist_man_MANS = \
 	vmod_blob.3 \
 	vmod_unix.3 \
 	vmod_proxy.3 \
-	vmod_h2.3
+	vmod_h2.3 \
+	vmod_math.3
 
 CLEANFILES = $(dist_man_MANS)
 
@@ -146,4 +147,8 @@ vmod_proxy.3: $(top_builddir)/vmod/vmod_proxy.man.rst
 vmod_h2.3: $(top_builddir)/vmod/vmod_h2.man.rst
 	$(BUILD_MAN) $? $@
 
+vmod_math.3: $(top_builddir)/vmod/vmod_math.man.rst
+	$(BUILD_MAN) $? $@
+
+
 .NOPATH: $(dist_man_MANS)

vmod/Makefile.am

@@ -33,6 +33,7 @@ include $(srcdir)/automake_boilerplate_h2.am
 include $(srcdir)/automake_boilerplate_cookie.am
 include $(srcdir)/automake_boilerplate_debug.am
 include $(srcdir)/automake_boilerplate_directors.am
+include $(srcdir)/automake_boilerplate_math.am
 include $(srcdir)/automake_boilerplate_proxy.am
 include $(srcdir)/automake_boilerplate_purge.am
 include $(srcdir)/automake_boilerplate_std.am
@@ -55,3 +56,17 @@ vmod_debug_symbols_regex = 'Vmod_.*_Data'
 
 # not --strict, not installed
 vmodtoolargs_debug = --boilerplate --noinst -o vcc_debug_if
+
+### vmod_math specific
+# the specs are deliberately checked in to not make the build
+# dependend on external connectivity
+vmod_math_spec.html:
+	curl -o $@ https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/math.h.html
+
+vmod_math.c: vmod_math.vcc
+
+vmod_math.vcc: vmod_math_spec.html vmod_math_gen.py
+	@PYTHON@ $(srcdir)/vmod_math_gen.py $< vmod_math.vcc vmod_math.c
+
+# avoid running curl when building from a dist
+dist_noinst_SCRIPTS = vmod_math_gen.py vmod_math_spec.html

vmod/automake_boilerplate_math.am

@@ -0,0 +1,41 @@
+## Generated by vmodtool.py --boilerplate.
+
+vmod_LTLIBRARIES += libvmod_math.la
+dist_vcc_DATA += $(srcdir)/vmod_math.vcc
+
+libvmod_math_la_SOURCES = \
+	vmod_math.c \
+	vmod_math_util.c
+
+libvmod_math_la_CFLAGS =
+
+vmodtoolargs_math ?= --strict --boilerplate -o vcc_math_if
+vmod_math_symbols_regex ?= Vmod_math_Data
+
+libvmod_math_la_LDFLAGS = \
+	-export-symbols-regex $(vmod_math_symbols_regex) \
+	$(AM_LDFLAGS) \
+	$(VMOD_LDFLAGS) \
+	-rpath $(vmoddir)
+
+nodist_libvmod_math_la_SOURCES = vcc_math_if.c vcc_math_if.h
+
+EXTRA_libvmod_math_la_DEPENDENCIES = $(nodist_libvmod_math_la_SOURCES)
+
+EXTRA_DIST += automake_boilerplate_math.am
+
+$(libvmod_math_la_OBJECTS): vcc_math_if.h
+
+vcc_math_if.h vmod_math.rst vmod_math.man.rst: vcc_math_if.c
+
+# A doc-change will not update mtime on the .h and .c files, so a
+# touch(1) is necessary to signal that vmodtool was in fact run.
+vcc_math_if.c: $(VMODTOOL) $(srcdir)/vmod_math.vcc
+	@PYTHON@ $(VMODTOOL) $(vmodtoolargs_math) $(srcdir)/vmod_math.vcc
+	touch vcc_math_if.c
+
+clean-local: clean-vmod-math
+
+clean-vmod-math:
+	rm -f $(nodist_libvmod_math_la_SOURCES)
+	rm -f vmod_math.rst vmod_math.man.rst

vmod/tests/math_b00000.vtc

@@ -0,0 +1,78 @@
+varnishtest vmod_math
+
+varnish v1 -vcl {
+	import math;
+
+	backend proforma none;
+
+	sub vcl_recv {
+		return (synth(200));
+	}
+
+	sub vcl_synth {
+		if (req.http.strfromdfmt) {
+			set resp.http.result = math.strfromd(req.http.strfromdfmt, math.constant(M_PI));
+			return (deliver);
+		}
+
+		# formatting basics
+		set resp.http."n.v" = 0.1;
+		set resp.http."n.13a" = math.strfromd("%.13a", 0.1);
+		set resp.http."n.17e" = math.strfromd("%.17e", 0.1);
+		set resp.http."n.17f" = math.strfromd("%.17f", 0.1);
+		set resp.http."n.g" = math.strfromd("%g", 0.1);
+
+		# edge cases where approx makes a difference
+
+		set resp.http."sinpi.v" = math.sin(math.constant(M_PI));
+		set resp.http."sinpi.17f" = math.strfromd("%.17f", math.sin(math.constant(M_PI)));
+		set resp.http."sinpi.0.equals" = math.sin(math.constant(M_PI)) == 0.0;
+		set resp.http."sinpi.0.approx" = math.approx(math.sin(math.constant(M_PI)), 0);
+		set resp.http."sinpi.0.zero" =
+			math.fpclassify(math.sin(math.constant(M_PI))) ==
+			math.fpclass(FP_ZERO);
+
+		# VRT_DECIMAL_MAX == 0x426d1a94a1fffff8
+		set resp.http."some1.v" = 999999999999 + 0.999;
+		set resp.http."some1.f" = math.strfromd("%f", 999999999999 + 0.999);
+		# VRT_DECIMAL_MAX - ULP == 0x426d1a94a1fffff7
+		set resp.http."some2.v" = 999999999999 + (9.989 / 10);
+		set resp.http."some2.f" = math.strfromd("%f", 999999999999 + (9.989 / 10));
+
+		set resp.http."some1.some2.equals" =
+			(999999999999 + 0.999) == (999999999999 + (9.989 / 10));
+		set resp.http."some1.some2.approx" =
+			math.approx(999999999999 + 0.999, 999999999999 + (9.989 / 10));
+
+		return (deliver);
+	}
+} -start
+
+client c1 {
+	txreq
+	rxresp
+	expect resp.status == 200
+
+	expect resp.http.n.v == 0.100
+	expect resp.http.n.13a == 0x1.999999999999ap-4
+	expect resp.http.n.17e == 1.00000000000000006e-01
+	expect resp.http.n.17f == 0.10000000000000001
+	expect resp.http.n.g == 0.1
+
+	expect resp.http.sinpi.v == 0.000
+	expect resp.http.sinpi.17f == 0.00000000000000012
+	expect resp.http.sinpi.0.equals == false
+	expect resp.http.sinpi.0.approx == true
+	expect resp.http.sinpi.0.zero == false
+
+	expect resp.http.some1.v == 999999999999.999
+	expect resp.http.some1.f == 999999999999.999023
+	expect resp.http.some2.v == 999999999999.999
+	expect resp.http.some2.f == 999999999999.998901
+	expect resp.http.some1.some2.equals == false
+	expect resp.http.some1.some2.approx == true
+
+	txreq -hdr "strfromdfmt: %5f"
+	rxresp
+	expect resp.status == 500
+} -run