From 2a02c74e13b9dcfc33ed4b03ca8dfbc76d52fd28 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Wed, 18 Nov 2026 13:12:08 -0500 Subject: [PATCH 1/4] Benchmark MIME (CRLF) decoding, each measurement in a fresh process. Measuring in one process let earlier allocations raise glibc's mmap threshold, which hid the cost of allocating large outputs. Each row now runs in a child process that reads its input from a file, with fastpybase64 timed first; --same-process restores the old behavior. --- bench.py | 94 ++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 81 insertions(+), 13 deletions(-) diff --git a/bench.py b/bench.py index df804ea..ec9716c 100644 --- a/bench.py +++ b/bench.py @@ -1,6 +1,6 @@ """Compare fastpybase64 with the standard library and pybase64. -Usage: python bench.py [--sizes 16,1024,1048576] [--time 0.2] +Usage: python bench.py [--sizes 16,1024,1048576] [--time 0.2] [--same-process] Throughput is reported in GB/s of *binary* (decoded) data for both encoding and decoding, so that the numbers of the two directions are comparable. For @@ -9,9 +9,13 @@ import argparse import base64 +import json +import os import platform import random +import subprocess import sys +import tempfile import timeit import fastpybase64 @@ -24,6 +28,11 @@ except ImportError: pybase64 = None + +def mime_crlf(raw): + return base64.encodebytes(raw).replace(b"\n", b"\r\n") + + # name -> (function name, keyword arguments, input preparation) OPERATIONS = { "b64encode": ("b64encode", {}, lambda raw: raw), @@ -33,6 +42,8 @@ "urlsafe_b64decode": ("urlsafe_b64decode", {}, base64.urlsafe_b64encode), "encodebytes": ("encodebytes", {}, lambda raw: raw), "decodebytes": ("decodebytes", {}, base64.encodebytes), + # MIME as found in email: lines of 76 characters ending with CRLF. + "b64decode(MIME CRLF)": ("b64decode", {}, mime_crlf), } DEFAULT_SIZES = [16, 64, 256, 1024, 4096, 65536, 1 << 20, 16 << 20] @@ -58,6 +69,45 @@ def call(): return min(timer.repeat(repeat=repeat, number=number)) / number +def measure_libraries(op, arg, size, min_time, repeat): + """Returns {library name: GB/s} for one operation on one input.""" + func_name, kwargs, _ = OPERATIONS[op] + names = [n for n, m in LIBRARIES.items() if hasattr(m, func_name)] + speeds, outputs = {}, {} + # fastpybase64 goes first, and the results are checked afterwards: the + # other libraries may free large temporary buffers, which would change + # the allocator's state (see run_in_child). + for name in sorted(names, key=lambda n: n != "fastpybase64"): + func = getattr(LIBRARIES[name], func_name) + outputs[name] = func(arg, **kwargs) + seconds = measure(func, arg, kwargs, min_time, repeat) + speeds[name] = size / seconds / 1e9 + expected = getattr(base64, func_name)(arg, **kwargs) + for name, output in outputs.items(): + assert output == expected, (name, op, size) + return speeds + + +def run_in_child(op, arg, size, args): + # Each measurement runs in a fresh process that reads its input from a + # file. The allocator remembers what was freed before: glibc raises its + # mmap threshold after freeing a large block, so building the input (or + # an earlier measurement) could hide the cost of allocating large + # outputs, a cost that a program decoding a file it just read does pay. + with tempfile.NamedTemporaryFile(suffix=".bench", delete=False) as f: + f.write(arg) + try: + out = subprocess.run( + [sys.executable, __file__, "--child", f.name, "--ops", op, + "--sizes", str(size), "--time", str(args.time), + "--repeat", str(args.repeat)], + check=True, stdout=subprocess.PIPE, text=True, + ).stdout + finally: + os.unlink(f.name) + return json.loads(out) + + def main(): parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument( @@ -70,10 +120,30 @@ def main(): parser.add_argument( "--ops", default=",".join(OPERATIONS), help="comma-separated operations" ) + parser.add_argument( + "--same-process", + action="store_true", + help="measure in this process (by default each measurement runs in a fresh one)", + ) + parser.add_argument("--child", metavar="FILE", help=argparse.SUPPRESS) args = parser.parse_args() sizes = [int(s) for s in args.sizes.split(",")] ops = args.ops.split(",") + for op in ops: + if op not in OPERATIONS: + parser.error(f"unknown operation {op!r}; choose among {', '.join(OPERATIONS)}") + + if args.child: + with open(args.child, "rb") as f: + arg = f.read() + speeds = measure_libraries(ops[0], arg, sizes[0], args.time, args.repeat) + print(json.dumps(speeds)) + return + print_header() + run(ops, sizes, args) + +def print_header(): print(f"Python {sys.version.split()[0]} on {platform.machine()} ({platform.platform()})") print( f"fastpybase64 {fastpybase64.__version__} " @@ -84,27 +154,25 @@ def main(): print(f"pybase64 {pybase64.get_version()}") print() print("Throughput in GB/s of binary data (higher is better).") - print() + print(flush=True) + +def run(ops, sizes, args): rng = random.Random(42) for op in ops: - func_name, kwargs, prepare = OPERATIONS[op] + func_name, _, prepare = OPERATIONS[op] print(f"### {op}") print() names = [n for n, m in LIBRARIES.items() if hasattr(m, func_name)] header = ["size"] + names + ["speedup vs stdlib", "speedup vs pybase64"] print("| " + " | ".join(header) + " |") - print("|" + "|".join("---:" for _ in header) + "|") + print("|" + "|".join("---:" for _ in header) + "|", flush=True) for size in sizes: - raw = rng.randbytes(size) - arg = prepare(raw) - expected = getattr(base64, func_name)(arg, **kwargs) - speeds = {} - for name in names: - func = getattr(LIBRARIES[name], func_name) - assert func(arg, **kwargs) == expected, (name, op, size) - seconds = measure(func, arg, kwargs, args.time, args.repeat) - speeds[name] = size / seconds / 1e9 + arg = prepare(rng.randbytes(size)) + if args.same_process: + speeds = measure_libraries(op, arg, size, args.time, args.repeat) + else: + speeds = run_in_child(op, arg, size, args) row = [human_size(size)] + [f"{speeds[n]:.2f}" for n in names] row.append(f"{speeds['fastpybase64'] / speeds['base64 (stdlib)']:.1f}x") if "pybase64" in speeds: From b2da4829b129d64f8a66bf2e8d39696c7ebc0e67 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Wed, 18 Nov 2026 13:12:08 -0500 Subject: [PATCH 2/4] Shorten decoded bytes in place when the slack is small. MIME input decodes to fewer bytes than the maximal length, and shrinking the result with _PyBytes_Resize trapped glibc into mmap'ing fresh pages on every call. Decoding 1 MiB of CRLF MIME on a Xeon 6548N goes from 3.1 to 12.1 GB/s. --- src/fastpybase64.cpp | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/fastpybase64.cpp b/src/fastpybase64.cpp index b78328c..3a9975d 100644 --- a/src/fastpybase64.cpp +++ b/src/fastpybase64.cpp @@ -368,7 +368,17 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { return nullptr; } if (r.count != max_length) { - if (_PyBytes_Resize(&result, Py_ssize_t(r.count)) != 0) { + // The maximal length counts spaces and line breaks as data, so MIME input + // (a line break every 76 characters) always decodes to fewer bytes. When + // the slack is small, shorten the bytes object in place instead of + // reallocating it. Reallocating made large MIME inputs several times + // slower with glibc: the block is mmap'ed, the shrink is an mremap, and + // the adaptive mmap threshold then learns the shrunk size, which is below + // the next request, so every call maps fresh pages and faults on them. + if (max_length - r.count <= max_length / 8) { + Py_SET_SIZE(result, Py_ssize_t(r.count)); + out[r.count] = '\0'; + } else if (_PyBytes_Resize(&result, Py_ssize_t(r.count)) != 0) { return nullptr; } } From c31fb658137fee2241b204397f23403976fa130c Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Wed, 18 Nov 2026 13:33:14 -0500 Subject: [PATCH 3/4] Add set_exact_sizing() to size decoded outputs exactly (off by default). The default keeps the in-place shrink, which may leave up to 1/8 of the allocation unused. Exact sizing computes the length with binary_length_from_base64 and decodes with base64_to_binary_safe; it wastes no memory but decodes more slowly. The tests run in both modes, and bench.py gains --exact-sizing. --- README.md | 18 +++++++++++ bench.py | 13 ++++++-- src/fastpybase64.cpp | 72 +++++++++++++++++++++++++++++++++++++++----- tests/conftest.py | 12 ++++++++ tests/test_base64.py | 22 ++++++++++++++ 5 files changed, 127 insertions(+), 10 deletions(-) create mode 100644 tests/conftest.py diff --git a/README.md b/README.md index f1197b0..b76d7ab 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ base64.encodebytes(data) # MIME: lines of 76 characters | `urlsafe_b64encode(s)`, `urlsafe_b64decode(s)` | alphabet with `-` and `_` | | `encodebytes(s)`, `decodebytes(s)` | MIME style: a newline after every 76 characters | | `get_implementation()` | the kernel simdutf selected for this processor (`icelake`, `haswell`, `arm64`, ...) | +| `set_exact_sizing(enabled)`, `get_exact_sizing()` | size decoded outputs exactly (off by default, see [Memory](#memory)) | | `simdutf_version`, `__version__` | versions of simdutf and of fastpybase64 | The functions accept what `base64` accepts: `bytes`, `bytearray`, @@ -81,6 +82,23 @@ the same message, and the rare inputs where `base64` is lenient in odd ways simdutf and then replacing the two characters; decoding with such an alphabet is left to `base64`. +### Memory + +A decoder does not know how many bytes it will produce until it has skipped +the spaces and line breaks, so fastpybase64 allocates the maximal length, +which counts them as data. When the result is shorter by at most 1/8, the +`bytes` object keeps its allocation: about 2.6% of it goes unused for MIME +input (a CRLF every 76 characters). Shrinking the allocation instead would +make large MIME inputs several times slower on Linux, because glibc would +then map fresh memory for every call. A larger difference (input that is +mostly spaces, for example) is given back. + +`fastpybase64.set_exact_sizing(True)` sizes every decoded output exactly, +with an extra pass over the input, so that no memory goes unused. Decoding +is then slower: on an Intel Xeon Gold 6548N, 1 MiB decodes at 14.0 GB/s +instead of 19.1 GB/s, and 1 MiB of MIME data at 8.5 GB/s instead of 12.0 +GB/s. The setting applies to the whole process. + ### Threads The GIL is released while encoding or decoding 64 KiB or more, so several diff --git a/bench.py b/bench.py index ec9716c..b897839 100644 --- a/bench.py +++ b/bench.py @@ -1,6 +1,7 @@ """Compare fastpybase64 with the standard library and pybase64. Usage: python bench.py [--sizes 16,1024,1048576] [--time 0.2] [--same-process] + [--exact-sizing] Throughput is reported in GB/s of *binary* (decoded) data for both encoding and decoding, so that the numbers of the two directions are comparable. For @@ -100,7 +101,8 @@ def run_in_child(op, arg, size, args): out = subprocess.run( [sys.executable, __file__, "--child", f.name, "--ops", op, "--sizes", str(size), "--time", str(args.time), - "--repeat", str(args.repeat)], + "--repeat", str(args.repeat)] + + (["--exact-sizing"] if args.exact_sizing else []), check=True, stdout=subprocess.PIPE, text=True, ).stdout finally: @@ -125,6 +127,11 @@ def main(): action="store_true", help="measure in this process (by default each measurement runs in a fresh one)", ) + parser.add_argument( + "--exact-sizing", + action="store_true", + help="call fastpybase64.set_exact_sizing(True) before measuring", + ) parser.add_argument("--child", metavar="FILE", help=argparse.SUPPRESS) args = parser.parse_args() sizes = [int(s) for s in args.sizes.split(",")] @@ -133,6 +140,7 @@ def main(): if op not in OPERATIONS: parser.error(f"unknown operation {op!r}; choose among {', '.join(OPERATIONS)}") + fastpybase64.set_exact_sizing(args.exact_sizing) if args.child: with open(args.child, "rb") as f: arg = f.read() @@ -148,7 +156,8 @@ def print_header(): print( f"fastpybase64 {fastpybase64.__version__} " f"(simdutf {fastpybase64.simdutf_version}, kernel: " - f"{fastpybase64.get_implementation()})" + f"{fastpybase64.get_implementation()}" + f"{', exact sizing' if fastpybase64.get_exact_sizing() else ''})" ) if pybase64 is not None: print(f"pybase64 {pybase64.get_version()}") diff --git a/src/fastpybase64.cpp b/src/fastpybase64.cpp index 3a9975d..99ecba0 100644 --- a/src/fastpybase64.cpp +++ b/src/fastpybase64.cpp @@ -10,6 +10,7 @@ #define PY_SSIZE_T_CLEAN #include +#include #include #define FASTPYBASE64_VERSION "0.1.4" @@ -23,6 +24,10 @@ namespace { // Release the GIL when processing at least this many bytes. constexpr Py_ssize_t kReleaseGilThreshold = 64 * 1024; +// set_exact_sizing(): size decoded outputs exactly (one more pass over the +// input) instead of allocating the maximal length. Process-wide. +std::atomic exact_sizing{false}; + // stdlib.encodebytes emits lines of at most 76 characters. constexpr size_t kMimeLineLength = 76; @@ -318,15 +323,34 @@ bool garbage_result_ok(const char *in, size_t length, size_t decoded, return true; } +// Decodes into out, which holds capacity bytes. On success, r.count is the +// number of bytes written. A capacity below the maximal binary length (exact +// sizing) requires the bounds-checked decoder. +simdutf::result decode_into(const InputView &input, char *out, + size_t capacity, size_t max_length, + simdutf::base64_options options) { + if (capacity >= max_length) { + return simdutf::base64_to_binary(input.data, input.length, out, options); + } + size_t written = capacity; + simdutf::result r = simdutf::base64_to_binary_safe( + input.data, input.length, out, written, options); + if (r.error == simdutf::error_code::SUCCESS) { + r.count = written; + } + return r; +} + simdutf::result run_decoder(const InputView &input, char *out, + size_t capacity, size_t max_length, simdutf::base64_options options) { simdutf::result r; if (Py_ssize_t(input.length) >= kReleaseGilThreshold) { Py_BEGIN_ALLOW_THREADS - r = simdutf::base64_to_binary(input.data, input.length, out, options); + r = decode_into(input, out, capacity, max_length, options); Py_END_ALLOW_THREADS } else { - r = simdutf::base64_to_binary(input.data, input.length, out, options); + r = decode_into(input, out, capacity, max_length, options); } return r; } @@ -340,7 +364,14 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { } size_t max_length = simdutf::maximal_binary_length_from_base64(input.data, input.length); - PyObject *result = PyBytes_FromStringAndSize(nullptr, Py_ssize_t(max_length)); + // With exact sizing, binary_length_from_base64 skips spaces and line + // breaks: the result is exact for valid input and an upper bound for any + // input (characters outside the alphabet are counted). + size_t capacity = max_length; + if (exact_sizing.load(std::memory_order_relaxed)) { + capacity = simdutf::binary_length_from_base64(input.data, input.length); + } + PyObject *result = PyBytes_FromStringAndSize(nullptr, Py_ssize_t(capacity)); if (result == nullptr) { return nullptr; } @@ -348,7 +379,7 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { simdutf::base64_options options = url ? simdutf::base64_default_or_url : simdutf::base64_default; - simdutf::result r = run_decoder(input, out, options); + simdutf::result r = run_decoder(input, out, capacity, max_length, options); bool ok; if (r.error == simdutf::error_code::SUCCESS) { ok = validate ? strict_result_ok(input.data, input.length, r.count) @@ -357,7 +388,7 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { // The input may contain characters that the standard library discards. options = url ? simdutf::base64_default_or_url_accept_garbage : simdutf::base64_default_accept_garbage; - r = run_decoder(input, out, options); + r = run_decoder(input, out, capacity, max_length, options); ok = r.error == simdutf::error_code::SUCCESS && garbage_result_ok(input.data, input.length, r.count, url); } else { @@ -367,15 +398,15 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { Py_DECREF(result); return nullptr; } - if (r.count != max_length) { + if (r.count != capacity) { // The maximal length counts spaces and line breaks as data, so MIME input // (a line break every 76 characters) always decodes to fewer bytes. When // the slack is small, shorten the bytes object in place instead of - // reallocating it. Reallocating made large MIME inputs several times + // reallocating it (set_exact_sizing(True) avoids the slack instead). Reallocating made large MIME inputs several times // slower with glibc: the block is mmap'ed, the shrink is an mremap, and // the adaptive mmap threshold then learns the shrunk size, which is below // the next request, so every call maps fresh pages and faults on them. - if (max_length - r.count <= max_length / 8) { + if (capacity - r.count <= capacity / 8) { Py_SET_SIZE(result, Py_ssize_t(r.count)); out[r.count] = '\0'; } else if (_PyBytes_Resize(&result, Py_ssize_t(r.count)) != 0) { @@ -564,6 +595,19 @@ PyObject *get_implementation(PyObject *, PyObject *) { return PyUnicode_FromStringAndSize(name.data(), Py_ssize_t(name.size())); } +PyObject *set_exact_sizing(PyObject *, PyObject *arg) { + int enabled = PyObject_IsTrue(arg); + if (enabled < 0) { + return nullptr; + } + exact_sizing.store(enabled != 0, std::memory_order_relaxed); + Py_RETURN_NONE; +} + +PyObject *get_exact_sizing(PyObject *, PyObject *) { + return PyBool_FromLong(exact_sizing.load(std::memory_order_relaxed)); +} + #define FASTCALL_KW(f) reinterpret_cast(reinterpret_cast(f)) PyMethodDef methods[] = { @@ -599,6 +643,18 @@ PyMethodDef methods[] = { {"get_implementation", get_implementation, METH_NOARGS, "get_implementation()\n--\n\n" "Return the name of the SIMD kernel selected by simdutf at runtime."}, + {"set_exact_sizing", set_exact_sizing, METH_O, + "set_exact_sizing(enabled, /)\n--\n\n" + "Size decoded outputs exactly (default: False).\n\n" + "By default, the decoders allocate the maximal output length, which\n" + "counts spaces and line breaks as data, and may leave up to 1/8 of the\n" + "allocation unused (about 2.6% for MIME input). With exact sizing, an\n" + "extra pass over the input computes the exact length: no memory is\n" + "wasted, but decoding is slower. The setting applies to the whole\n" + "process."}, + {"get_exact_sizing", get_exact_sizing, METH_NOARGS, + "get_exact_sizing()\n--\n\n" + "Return whether decoded outputs are sized exactly."}, {nullptr, nullptr, 0, nullptr}, }; diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..7f9c8ba --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,12 @@ +import pytest + +import fastpybase64 + + +@pytest.fixture(autouse=True, params=[False, True], ids=["default", "exact-sizing"]) +def sizing(request): + """Runs every test with and without exact output sizing.""" + previous = fastpybase64.get_exact_sizing() + fastpybase64.set_exact_sizing(request.param) + yield request.param + fastpybase64.set_exact_sizing(previous) diff --git a/tests/test_base64.py b/tests/test_base64.py index 746687e..458f8b8 100644 --- a/tests/test_base64.py +++ b/tests/test_base64.py @@ -258,3 +258,25 @@ def test_large_with_noise(): check_decoders(encoded) check_decoders(encoded.replace(b"\n", b"!\n")) check_decoders(encoded + b"YQ==") + + +def test_exact_sizing_setting(sizing): + assert fastpybase64.get_exact_sizing() is sizing + fastpybase64.set_exact_sizing(0) + assert fastpybase64.get_exact_sizing() is False + fastpybase64.set_exact_sizing([1]) + assert fastpybase64.get_exact_sizing() is True + with pytest.raises(TypeError): + fastpybase64.set_exact_sizing() + + +@pytest.mark.parametrize("length", [0, 1, 2, 3, 57, 1000, 1 << 20]) +def test_mime_crlf(length): + data = random.Random(length).randbytes(length) + encoded = base64.encodebytes(data).replace(b"\n", b"\r\n") + check_decoders(encoded) + check_decoders(b" \r\n\t" + encoded + b"\r\n \r\n") + + +def test_only_whitespace(): + check_decoders(b" \r\n" * 1000) From 6e65e19f454603e9fa1696a2f65edb5a35fddac4 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Wed, 18 Nov 2026 14:34:19 -0500 Subject: [PATCH 4/4] Say that exact sizing is exact for valid input. --- README.md | 14 +++++++++----- src/fastpybase64.cpp | 7 ------- 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index b76d7ab..cdbf81d 100644 --- a/README.md +++ b/README.md @@ -93,11 +93,15 @@ make large MIME inputs several times slower on Linux, because glibc would then map fresh memory for every call. A larger difference (input that is mostly spaces, for example) is given back. -`fastpybase64.set_exact_sizing(True)` sizes every decoded output exactly, -with an extra pass over the input, so that no memory goes unused. Decoding -is then slower: on an Intel Xeon Gold 6548N, 1 MiB decodes at 14.0 GB/s -instead of 19.1 GB/s, and 1 MiB of MIME data at 8.5 GB/s instead of 12.0 -GB/s. The setting applies to the whole process. +`fastpybase64.set_exact_sizing(True)` sizes every decoded output exactly +for valid input, with an extra pass over the input, so that no memory goes +unused. Valid input contains only base64 alphabet characters, `=` padding, +and ASCII whitespace: any byte at or below 0x20, which covers a CRLF every +76 characters. A byte above 0x20 and outside the alphabet is counted in +that length and then ignored, so the allocation can be larger than the +output. Decoding is then slower: on an Intel Xeon Gold 6548N, 1 MiB decodes +at 14.0 GB/s instead of 19.1 GB/s, and 1 MiB of MIME data at 8.5 GB/s +instead of 12.0 GB/s. The setting applies to the whole process. ### Threads diff --git a/src/fastpybase64.cpp b/src/fastpybase64.cpp index 99ecba0..12aed5b 100644 --- a/src/fastpybase64.cpp +++ b/src/fastpybase64.cpp @@ -399,13 +399,6 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) { return nullptr; } if (r.count != capacity) { - // The maximal length counts spaces and line breaks as data, so MIME input - // (a line break every 76 characters) always decodes to fewer bytes. When - // the slack is small, shorten the bytes object in place instead of - // reallocating it (set_exact_sizing(True) avoids the slack instead). Reallocating made large MIME inputs several times - // slower with glibc: the block is mmap'ed, the shrink is an mremap, and - // the adaptive mmap threshold then learns the shrunk size, which is below - // the next request, so every call maps fresh pages and faults on them. if (capacity - r.count <= capacity / 8) { Py_SET_SIZE(result, Py_ssize_t(r.count)); out[r.count] = '\0';