Add benchmarking info

Author: ZipFile

BENCHMARK.rst

@@ -0,0 +1,99 @@
+============
+Benchmarking
+============
+
+As of Mar 2026, there are 2 alternative implementations of SonyFlake in
+Python:
+
+* `hjpotter92/sonyflake-py <https://github.com/hjpotter92/sonyflake-py>`_
+* `iyad-f/sonyflake <https://github.com/iyad-f/sonyflake>`_
+
+None of them has batch generation feature, neither they use extension modules
+for speed ups. So we'll be comparing against pure-Python, single-id generation
+mode in ``sonyflake-turbo``:
+
+.. code-block:: python
+
+    sf = SonyFlake(*range(0xFFFF))
+    asf = AsyncSonyFlake(sf)
+    next(sf)  # for sync benchmarks
+    await asf  # for async benchmarks
+
+Since Sonyflake algorithm at its core has limited throughput, we'll be using
+as much machine ids as possible. For ``sonyflake-turbo`` it is as trivial
+as:
+
+.. code-block:: python
+
+    sf = SonyFlake(*range(0xFFFF))
+
+for other implementation we'll be using something equivalent to:
+
+.. code-block:: python
+
+    sfs = [
+        SonyFlake(machine_id=machine_id).next_id
+        for machine_id in range(0xFFFF)
+    ]
+    max_i = len(sfs)
+    i = 0
+
+    def next_id() -> int:
+        nonlocal i
+        id_ = sfs[i]()
+        i = (i + 1) % max_i
+        return id_
+
+
+In order to shave-off some time for ``getattr``-ing of ``next_id`` we do it
+in initialization step. Same goes for ``len``-s. We're not using generators,
+since ``yield``-s are also tanking performance.
+
+This setup is closest to "running multiple generators in parallel".
+
+Unfortunately, both ``hjpotter92/sonyflake-py`` and ``iyad-f/sonyflake``
+share the same package name ``sonyflake``, so we cannot benchmark everything
+in one go. Results has to be merged later.
+
+Full source code of benchmark is located in ``benchmark.py`` file in the root
+of the repo.
+
+Naming breakdown:
+
+* ``sonyflake_py`` - ``hjpotter92/sonyflake-py``
+* ``sonyflake_alt*`` - ``iyad-f/sonyflake``
+* ``turbo_native*`` - running against ``sonyflake_turbo._sonyflake.SonyFlake``
+* ``turbo_pure*`` - running against ``sonyflake_turbo.pure.SonyFlake``
+* ``turbo_*_solo`` - solo mode (``next(sf)``, ``await asf``)
+* ``turbo_*_batch`` - batch mode (``sf(1000)``, ``await asf(1000)``)
+
+Run:
+
+.. code-block:: sh
+
+    python benchmark.py
+
+Results
+=======
+
+For CPython 3.12.3 on the Intel Xeon E3-1275, results are following (lower %
+= better):
+
+.. csv-table:: Sync
+    :header: "Name", "Time", "%"
+
+    turbo_native_batch,0.03s,3.03%
+    turbo_native_solo,0.13s,13.13%
+    turbo_pure_batch,0.35s,35.35%
+    turbo_pure_solo,0.99s,100.00%
+    sonyflake_py,1.35s,136.36%
+    sonyflake_alt,2.48s,250.51%
+
+.. csv-table:: Async
+    :header: "Name", "Time", "%"
+
+    turbo_native_batch_async,0.05s,0.41%
+    turbo_native_solo_async,10.16s,83.07%
+    turbo_pure_batch_async,0.31s,2.53%
+    turbo_pure_solo_async,12.23s,100.00%
+    sonyflake_alt_async,14.07s,115.04%

README.rst

@@ -247,6 +247,11 @@ Otherwise you might want to use it for one of the following reasons:
 .. _UUIDv7: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
 .. _IDOR: https://cheatsheetseries.owasp.org/cheatsheets/Insecure_Direct_Object_Reference_Prevention_Cheat_Sheet.html
 
+Benchmarking
+~~~~~~~~~~~~
+
+See the `benchmarks <BENCHMARK.rst>`_ for performance details.
+
 Development
 ===========
 

benchmark.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+import platform
+import sys
+from asyncio import new_event_loop, set_event_loop
+from contextlib import suppress
+from datetime import datetime, timezone
+from timeit import timeit
+
+from sonyflake_turbo import AsyncSonyFlake
+
+EPOCH = 1749081600
+EPOCH_DT = datetime.fromtimestamp(EPOCH, tz=timezone.utc)
+ONE_THOUSAND = 1000
+ONE_MILLION = ONE_THOUSAND * ONE_THOUSAND
+# Benchmarking a single id generator is not useful since it'll be bottlenecked
+# by SonyFlake's own throughtput. Use all possible machine ids to alleviate
+# stray sleeps.
+MACHINE_IDS = range(0xFFFF)
+# `asyncio.run()` creates new event loop on every invocation, which is no-go
+# for benchmarking. Reuse the same event loop for all benchmarks.
+loop = new_event_loop()
+set_event_loop(loop)
+
+
+def _turbo(name, sf):
+    t_batch = timeit(lambda: sf(ONE_THOUSAND), number=ONE_THOUSAND)
+    t_solo = timeit(lambda: next(sf), number=ONE_MILLION)
+
+    print(f"turbo_{name}_batch,{t_batch:.2f}")
+    print(f"turbo_{name}_solo,{t_solo:.2f}")
+
+
+def _turbo_async(name, asf):
+    def batch():
+        loop.run_until_complete(asf(ONE_THOUSAND))
+
+    def solo():
+        loop.run_until_complete(asf)
+
+    t_batch = timeit(batch, number=ONE_THOUSAND)
+    t_solo = timeit(solo, number=ONE_MILLION)
+
+    print(f"turbo_{name}_batch_async,{t_batch:.2f}")
+    print(f"turbo_{name}_solo_async,{t_solo:.2f}")
+
+
+def turbo_native():
+    from sonyflake_turbo._sonyflake import SonyFlake
+
+    _turbo("native", SonyFlake(*MACHINE_IDS, start_time=EPOCH))
+
+
+def turbo_pure():
+    from sonyflake_turbo.pure import SonyFlake
+
+    _turbo("pure", SonyFlake(*MACHINE_IDS, start_time=EPOCH))
+
+
+def turbo_async_native():
+    from sonyflake_turbo._sonyflake import SonyFlake
+
+    asf = AsyncSonyFlake(SonyFlake(*MACHINE_IDS, start_time=EPOCH))
+
+    _turbo_async("native", asf)
+
+
+def turbo_async_pure():
+    from sonyflake_turbo.pure import SonyFlake
+
+    asf = AsyncSonyFlake(SonyFlake(*MACHINE_IDS, start_time=EPOCH))
+
+    _turbo_async("pure", asf)
+
+
+def sonyflake_py():
+    """pip install sonyflake-py"""
+
+    from sonyflake import SonyFlake
+
+    sfs = [
+        SonyFlake(start_time=EPOCH_DT, machine_id=lambda: machine_id).next_id
+        for machine_id in MACHINE_IDS
+    ]
+    max_i = len(sfs)
+    i = 0
+
+    def next_id() -> int:
+        nonlocal i
+        id_ = sfs[i]()
+        i = (i + 1) % max_i
+        return id_
+
+    t = timeit(next_id, number=ONE_MILLION)
+
+    print(f"sonyflake_py,{t:.2f}")
+
+
+def sonyflake_alt():
+    """pip install sonyflake"""
+
+    from sonyflake import Sonyflake
+
+    sfs = [
+        Sonyflake(start_time=EPOCH_DT, machine_id=machine_id).next_id
+        for machine_id in MACHINE_IDS
+    ]
+    max_i = len(sfs)
+    i = 0
+
+    def next_id() -> int:
+        nonlocal i
+        id_ = sfs[i]()
+        i = (i + 1) % max_i
+        return id_
+
+    t = timeit(next_id, number=ONE_MILLION)
+
+    print(f"sonyflake_alt,{t:.2f}")
+
+
+def sonyflake_alt_async():
+    """pip install sonyflake"""
+
+    from sonyflake import Sonyflake
+
+    sfs = [
+        Sonyflake(start_time=EPOCH_DT, machine_id=machine_id).next_id_async
+        for machine_id in MACHINE_IDS
+    ]
+    max_i = len(sfs)
+    i = 0
+
+    def next_id() -> int:
+        nonlocal i
+        id_ = loop.run_until_complete(sfs[i]())
+        i = (i + 1) % max_i
+        return id_
+
+    t = timeit(next_id, number=ONE_MILLION)
+
+    print(f"sonyflake_alt_async,{t:.2f}")
+
+
+def main():
+    print(platform.python_implementation(), platform.python_version(), file=sys.stderr)
+    for f in [
+        turbo_native,
+        turbo_pure,
+        turbo_async_native,
+        turbo_async_pure,
+        sonyflake_py,
+        sonyflake_alt,
+        sonyflake_alt_async,
+    ]:
+        with suppress(ImportError):
+            f()
+    print("done", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
+    # CPython 3.12.3
+    # turbo_native_batch,0.03
+    # turbo_native_solo,0.13
+    # turbo_pure_batch,0.35
+    # turbo_pure_solo,0.99
+    # turbo_native_batch_async,0.05
+    # turbo_native_solo_async,10.16
+    # turbo_pure_batch_async,0.31
+    # turbo_pure_solo_async,12.23
+    # sonyflake_py,1.35
+    # sonyflake_alt,2.48
+    # sonyflake_alt_async,14.07