[WIP] gh-129813, PEP 782: Add PyBytesWriter C API

[vstinner]

Add functions:

• PyBytesWriter_Create()
• PyBytesWriter_Discard()
• PyBytesWriter_Finish()
• PyBytesWriter_FinishWithSize()
• PyBytesWriter_FinishWithEndPointer()
• PyBytesWriter_Data()
• PyBytesWriter_Allocated()
• PyBytesWriter_SetSize()
• PyBytesWriter_Resize()

• Issue: [C API] PEP 782: Add PyBytesWriter API #129813

[vstinner]

This change has no impact on performance, even if the new public API allocates memory on the heap, instead of allocating on the stack. It uses a freelist to optimize PyBytesWriter_Create().

Microbenchmark on 3 functions, to compare the private _PyBytesWriter (ref) to the new public PyBytesWriter (change):

• bytes(list)
• bytes.fromhex(str)
• binascii.b2a_uu(bytes)

import pyperf
import binascii

runner = pyperf.Runner()
runner.bench_func('from list 100', bytes, list(b'x' * 100))
runner.bench_func('from list 1,000', bytes, list(b'x' * 1_000))

runner.bench_func('from hex 100', bytes.fromhex, bytes(range(100)).hex())
runner.bench_func('from hex 1,000', bytes.fromhex, (b'x' * 1_000).hex())

runner.bench_func('b2a_uu', binascii.b2a_uu, b'x' * 45)

Result:

Benchmark	ref	change
from list 100	631 ns	623 ns: 1.01x faster
from hex 100	141 ns	145 ns: 1.03x slower
from hex 1,000	1.03 us	1.04 us: 1.00x slower
b2a_uu	112 ns	111 ns: 1.01x faster
Geometric mean	(ref)	1.00x slower

Benchmark hidden because not significant (1): from list 1,000

[vstinner]

Benchmark comparing PyBytes_FromStringAndSize(NULL, length) (ref) to PyBytesWriter_Create() (change).

Benchmark:

import pyperf

SIZES = (10, 100, 500)

runner = pyperf.Runner()
for size in SIZES:
    large_int = (2 ** (size * 8) - 1)
    runner.bench_func(f'to_bytes({size})', large_int.to_bytes, size)
for size in SIZES:
    mem = memoryview(b'x' * size)
    runner.bench_func(f'memoryview({size}).tobytes()', mem.tobytes)

Result:

Benchmark	ref	change
to_bytes(10)	56.3 ns	66.4 ns: 1.18x slower (+10.1 ns)
to_bytes(100)	152 ns	162 ns: 1.06x slower (+10 ns)
to_bytes(500)	563 ns	559 ns: 1.01x faster (+4 ns)
memoryview(10).tobytes()	37.5 ns	47.0 ns: 1.25x slower (+9.5 ns)
memoryview(100).tobytes()	35.3 ns	46.6 ns: 1.32x slower (+11.3 ns)
memoryview(500).tobytes()	45.5 ns	55.3 ns: 1.21x slower (+9.8 ns)
Geometric mean	(ref)	1.16x slower

It's hard to beat PyBytes_FromStringAndSize(NULL, length) performance, since PyBytesWriter_Create() is a wrapper built on top of PyBytes_FromStringAndSize(NULL, length).

There is an overhead around 10 ns when using PyBytesWriter.

[serhiy-storchaka]

Could you please benchmark the following?

• ASCII, Latin1 and UTF-8 encoders. For ASCII-only and non-ASCII data.
• The backslashreplace and xmlcharrefreplace error handlers (encoding).
• PyBytes_FromFormat(). Especially with few % formats and large raw data between them.
• PyBytes_DecodeEscape().

[vstinner]

I wrote a big PR to show how PEP 782 would look like and how it's being used. But if PEP 782 is accepted, I will only start by adding the API without using it. Then I will write separated changes to use the new API and run benchmarks on each change.

ASCII, Latin1 and UTF-8 encoders. For ASCII-only and non-ASCII data.

I didn't modify these encoders, they still use the private _PyBytesWriter API.

The backslashreplace and xmlcharrefreplace error handlers (encoding).

Same.

If I modify these encoders and error handlers later, I will run benchmarks to decide if it's acceptable to use the public API or not.

[vstinner]

Microbenchmark on PyBytes_FromFormat() and PyBytes_DecodeEscape() functions.

Details

import pyperf
runner = pyperf.Runner()

import ctypes
from ctypes import pythonapi, py_object
from ctypes import (
    c_int, c_uint,
    c_long, c_ulong,
    c_size_t, c_ssize_t,
    c_char_p)

PyBytes_FromFormat = pythonapi.PyBytes_FromFormat
PyBytes_FromFormat.argtypes = (c_char_p,)
PyBytes_FromFormat.restype = py_object

PyBytes_DecodeEscape = pythonapi.PyBytes_DecodeEscape
PyBytes_DecodeEscape.argtypes = (c_char_p, c_size_t, c_char_p, c_size_t, c_char_p)
PyBytes_DecodeEscape.restype = py_object

runner.bench_func('Format hello world', PyBytes_FromFormat, b'Hello %s !', b'world')
fmt = (b'Hell%c' + b' ' * 1024 + b' %s')
runner.bench_func('Format long format', PyBytes_FromFormat, fmt, c_int(ord('o')), b'world')

s = b'abc\\ndef\\x40.'
runner.bench_func('Decode simple', PyBytes_DecodeEscape, s, len(s), None, 0, b'unused')
s = b'x' * 1024
runner.bench_func('Decode long copy', PyBytes_DecodeEscape, s, len(s), None, 0, b'unused')
s = b'\\x40' * 1024
runner.bench_func('Decode long \\x40', PyBytes_DecodeEscape, s, len(s), None, 0, b'unused')

Results:

Benchmark	ref	pep782
Format long format	1.06 us	1.04 us: 1.02x faster
Decode simple	776 ns	743 ns: 1.04x faster
Decode long copy	1.38 us	1.34 us: 1.03x faster
Decode long \x40	2.70 us	2.67 us: 1.01x faster
Geometric mean	(ref)	1.02x faster

Benchmark hidden because not significant (1): Format hello world

I'm not sure why PEP 782 is faster, but at least it's not slower :-)

I build Python with gcc -O3 (without PGO, LTO, CPU isolation).

[vstinner]

I started to split this huge PR into smaller PRs, see PRs attached to the issue #129813.