Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -81,6 +82,27 @@ 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
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

The GIL is released while encoding or decoding 64 KiB or more, so several
Expand Down
105 changes: 91 additions & 14 deletions bench.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
"""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]
[--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
Expand All @@ -9,9 +10,13 @@

import argparse
import base64
import json
import os
import platform
import random
import subprocess
import sys
import tempfile
import timeit

import fastpybase64
Expand All @@ -24,6 +29,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),
Expand All @@ -33,6 +43,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]
Expand All @@ -58,6 +70,46 @@ 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)]
+ (["--exact-sizing"] if args.exact_sizing else []),
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(
Expand All @@ -70,41 +122,66 @@ 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(
"--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(",")]
ops = args.ops.split(",")
for op in ops:
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()
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__} "
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()}")
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:
Expand Down
73 changes: 66 additions & 7 deletions src/fastpybase64.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
#define PY_SSIZE_T_CLEAN
#include <Python.h>

#include <atomic>
#include <cstring>

#define FASTPYBASE64_VERSION "0.1.4"
Expand All @@ -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<bool> exact_sizing{false};

// stdlib.encodebytes emits lines of at most 76 characters.
constexpr size_t kMimeLineLength = 76;

Expand Down Expand Up @@ -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;
}
Expand All @@ -340,15 +364,22 @@ 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;
}
char *out = PyBytes_AS_STRING(result);

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)
Expand All @@ -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 {
Expand All @@ -367,8 +398,11 @@ PyObject *try_decode(const InputView &input, bool url, bool validate) {
Py_DECREF(result);
return nullptr;
}
if (r.count != max_length) {
if (_PyBytes_Resize(&result, Py_ssize_t(r.count)) != 0) {
if (r.count != capacity) {
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) {
return nullptr;
}
}
Expand Down Expand Up @@ -554,6 +588,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<PyCFunction>(reinterpret_cast<void (*)(void)>(f))

PyMethodDef methods[] = {
Expand Down Expand Up @@ -589,6 +636,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},
};

Expand Down
12 changes: 12 additions & 0 deletions tests/conftest.py
Original file line number Diff line number Diff line change
@@ -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)
22 changes: 22 additions & 0 deletions tests/test_base64.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading