fastsimdjson 0.4.0__tar.gz → 0.6.0__tar.gz

{fastsimdjson-0.4.0/src/fastsimdjson.egg-info → fastsimdjson-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastsimdjson
-Version: 0.4.0
+Version: 0.6.0
 Summary: Fast JSON parsing for Python, built on simdjson
 Author-email: Daniel Lemire <daniel@lemire.me>
 License-Expression: Apache-2.0
@@ -197,6 +197,42 @@ returned, otherwise `JSONDecodeError` reports `json`'s message and the
 position in the whole input. A truncated last document is an error. The
 views returned by `parse_many` remain valid after the iterator moves on.
 
+### Streams on several threads: `threads=N` and `map_many`
+
+On free-threaded Python (3.14t and newer), a stream can be parsed by several
+threads at once:
+
+```python
+docs = fastsimdjson.loads_many(data, threads=16)        # a list, in order
+views = fastsimdjson.parse_many(data, threads=16)       # a list of views
+# fn runs in the threads too, on each document; its results, in order:
+scores = fastsimdjson.map_many(score, data, threads=16)
+```
+
+With `threads`, `loads_many` and `parse_many` return a list of all the
+documents instead of an iterator. `map_many(fn, data, **kw)` returns
+`[fn(doc) for doc in loads_many(data, **kw)]` (`parse_many` with
+`lazy=True`), with `fn` called in the threads. `threads=0` (or `None`) uses
+one thread per processor; small inputs use fewer threads (about one per
+512 KB). The input is cut into chunks at newlines (before each `\x1e` for
+`json_seq`), so `threads` works with the formats `"whitespace"`, `"lines"`
+and `"json_seq"`.
+
+The results, and the exceptions, are those of one thread: when a chunk
+contains an error or a document that only `json` accepts, the documents
+before it are kept and the rest is parsed in the calling thread, as without
+threads. An exception raised by `fn` is raised again, for the first document
+where it happened; `fn` may then have been called on later documents, in
+other threads, and it must be safe to call from several threads at once.
+
+The worker threads are started by the first call that needs them and kept
+for later calls (they wait, detached from the interpreter, between calls,
+and stop at exit). `map_many` scales best: each document is built, used and
+freed in the same thread, and only `fn`'s results come back. `loads_many` must return every
+document, and the Python objects of all of them, to the calling thread.
+With the GIL (the default build of Python), the calling thread does all the
+work: `threads` has no effect on speed.
+
 ### `release`
 
 `release()` frees the simdjson parser and the string caches kept by the
@@ -433,6 +469,24 @@ msgspec's `decode_lines` and `loads_many` are on par (`loads_many` is about 2%
 faster). `parse_many` only creates the views; reading values from them adds to
 its time.
 
+### Streams on several threads
+
+300 MB of NDJSON (146,624 records: tweets, GitHub events, citm performances,
+gsoc and update-center entries), free-threaded Python 3.14.6, collector
+disabled (see below), Intel Xeon Gold 6548N (64 cores); GB/s:
+
+| threads | 1 | 2 | 4 | 8 | 16 | 32 | 64 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| `map_many(len, data, threads=N)` | 1.03 | 1.78 | 3.66 | 6.82 | 13.0 | 23.7 | **28.8** |
+| `parse_many(data, threads=N)` | 2.00 | 2.84 | 5.28 | 9.26 | 16.1 | 22.7 | 25.8 |
+| `loads_many(data, threads=N)` | 0.90 | 1.44 | 2.79 | 4.99 | 8.98 | 13.3 | 15.4 |
+
+`map_many` is 28 times faster on 64 threads than on one (up to 38 GB/s when
+nothing else runs in the process). `loads_many` builds every document for
+the calling thread and is 17 times faster. With the collector enabled,
+Python collects after the call returns: it examines the millions of objects
+just created, which takes about 0.1 s here, with or without threads.
+
 ## Limitations
 
 * The simdjson parser and the key and string caches are thread-local.

{fastsimdjson-0.4.0 → fastsimdjson-0.6.0}/README.md

@@ -166,6 +166,42 @@ returned, otherwise `JSONDecodeError` reports `json`'s message and the
 position in the whole input. A truncated last document is an error. The
 views returned by `parse_many` remain valid after the iterator moves on.
 
+### Streams on several threads: `threads=N` and `map_many`
+
+On free-threaded Python (3.14t and newer), a stream can be parsed by several
+threads at once:
+
+```python
+docs = fastsimdjson.loads_many(data, threads=16)        # a list, in order
+views = fastsimdjson.parse_many(data, threads=16)       # a list of views
+# fn runs in the threads too, on each document; its results, in order:
+scores = fastsimdjson.map_many(score, data, threads=16)
+```
+
+With `threads`, `loads_many` and `parse_many` return a list of all the
+documents instead of an iterator. `map_many(fn, data, **kw)` returns
+`[fn(doc) for doc in loads_many(data, **kw)]` (`parse_many` with
+`lazy=True`), with `fn` called in the threads. `threads=0` (or `None`) uses
+one thread per processor; small inputs use fewer threads (about one per
+512 KB). The input is cut into chunks at newlines (before each `\x1e` for
+`json_seq`), so `threads` works with the formats `"whitespace"`, `"lines"`
+and `"json_seq"`.
+
+The results, and the exceptions, are those of one thread: when a chunk
+contains an error or a document that only `json` accepts, the documents
+before it are kept and the rest is parsed in the calling thread, as without
+threads. An exception raised by `fn` is raised again, for the first document
+where it happened; `fn` may then have been called on later documents, in
+other threads, and it must be safe to call from several threads at once.
+
+The worker threads are started by the first call that needs them and kept
+for later calls (they wait, detached from the interpreter, between calls,
+and stop at exit). `map_many` scales best: each document is built, used and
+freed in the same thread, and only `fn`'s results come back. `loads_many` must return every
+document, and the Python objects of all of them, to the calling thread.
+With the GIL (the default build of Python), the calling thread does all the
+work: `threads` has no effect on speed.
+
 ### `release`
 
 `release()` frees the simdjson parser and the string caches kept by the
@@ -402,6 +438,24 @@ msgspec's `decode_lines` and `loads_many` are on par (`loads_many` is about 2%
 faster). `parse_many` only creates the views; reading values from them adds to
 its time.
 
+### Streams on several threads
+
+300 MB of NDJSON (146,624 records: tweets, GitHub events, citm performances,
+gsoc and update-center entries), free-threaded Python 3.14.6, collector
+disabled (see below), Intel Xeon Gold 6548N (64 cores); GB/s:
+
+| threads | 1 | 2 | 4 | 8 | 16 | 32 | 64 |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| `map_many(len, data, threads=N)` | 1.03 | 1.78 | 3.66 | 6.82 | 13.0 | 23.7 | **28.8** |
+| `parse_many(data, threads=N)` | 2.00 | 2.84 | 5.28 | 9.26 | 16.1 | 22.7 | 25.8 |
+| `loads_many(data, threads=N)` | 0.90 | 1.44 | 2.79 | 4.99 | 8.98 | 13.3 | 15.4 |
+
+`map_many` is 28 times faster on 64 threads than on one (up to 38 GB/s when
+nothing else runs in the process). `loads_many` builds every document for
+the calling thread and is 17 times faster. With the collector enabled,
+Python collects after the call returns: it examines the millions of objects
+just created, which takes about 0.1 s here, with or without threads.
+
 ## Limitations
 
 * The simdjson parser and the key and string caches are thread-local.

{fastsimdjson-0.4.0 → fastsimdjson-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastsimdjson"
-version = "0.4.0"
+version = "0.6.0"
 description = "Fast JSON parsing for Python, built on simdjson"
 readme = "README.md"
 authors = [