From 23fbd9d004553637a91cabd497fb9cc0a40d90b6 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Sun, 14 Jun 2020 18:28:09 -0400 Subject: [PATCH] Some tweaks. --- doc/basics.md | 4 ++-- doc/parse_many.md | 4 ++++ doc/performance.md | 18 +++++++++++++++++- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/doc/basics.md b/doc/basics.md index c56eb6a7..2f5c7f9f 100644 --- a/doc/basics.md +++ b/doc/basics.md @@ -513,6 +513,6 @@ parser for your CPU, is transparent and thread-safe. Backwards Compatibility ----------------------- -The only header file supported by simdjson is simdjson.h. Older versions of simdjson published a -number of other include files such as document.h or ParsedJson.h alongside simdjson.h; these headers +The only header file supported by simdjson is `simdjson.h`. Older versions of simdjson published a +number of other include files such as `document.h` or `ParsedJson.h` alongside `simdjson.h`; these headers may be moved or removed in future versions. diff --git a/doc/parse_many.md b/doc/parse_many.md index 9419f3fb..2316fd88 100644 --- a/doc/parse_many.md +++ b/doc/parse_many.md @@ -97,6 +97,10 @@ of magnitude cheaper. Ain't that awesome! Thread support is only active if thread supported is detected in which case the macro SIMDJSON_THREADS_ENABLED is set. Otherwise the library runs in single-thread mode. +A `document_stream` instance uses at most two threads: there is a main thread and a worker thread. +You should expect the main thread to be fully occupied while the worker thread is partially busy +(e.g., 80% of the time). + Support ------- diff --git a/doc/performance.md b/doc/performance.md index bc58eeab..f4b5153a 100644 --- a/doc/performance.md +++ b/doc/performance.md @@ -11,13 +11,16 @@ are still some scenarios where tuning can enhance performance. * [Computed GOTOs](#computed-gotos) * [Number parsing](#number-parsing) * [Visual Studio](#visual-studio) +* [Downclocking](#downclocking) + Reusing the parser for maximum efficiency ----------------------------------------- If you're using simdjson to parse multiple documents, or in a loop, you should make a parser once and reuse it. The simdjson library will allocate and retain internal buffers between parses, keeping -buffers hot in cache and keeping memory allocation and initialization to a minimum. +buffers hot in cache and keeping memory allocation and initialization to a minimum. In this manner, +you can parse terabytes of JSON data without doing any allocation. ```c++ dom::parser parser; @@ -152,3 +155,16 @@ On Intel and AMD Windows platforms, Microsoft Visual Studio enables programmers We do not recommend that you compile simdjson with architecture-specific flags such as `arch:AVX2`. The simdjson library automatically selects the best execution kernel at runtime. Recent versions of Microsoft Visual Studio on Windows provides support for the LLVM Clang compiler. You only need to install the "Clang compiler" optional component. You may also get a copy of the 64-bit LLVM CLang compiler for [Windows directly from LLVM](https://releases.llvm.org/download.html). The simdjson library fully supports the LLVM Clang compiler under Windows. In fact, you may get better performance out of simdjson with the LLVM Clang compiler than with the regular Visual Studio compiler. + + +Downclocking +-------------- + +On some Intel processors, using SIMD instructions in a sustained manner on the same CPU core may result in a phenomenon called downclocking whereas the processor initially runs these instructions at a slow speed before reducing the frequency of the core for a short time (milliseconds). Intel refers to these states as licenses. On some current Intel processors, it occurs under two scenarios: + +- [Whenever 512-bit AVX-512 instructions are used](https://lemire.me/blog/2018/09/07/avx-512-when-and-how-to-use-these-new-instructions/). +- Whenever heavy 256-bit or wider instructions are used. Heavy instructions are those involving floating point operations or integer multiplications (since these execute on the floating point unit). + +The simdjson library does not currently support AVX-512 instructions and it does not make use of heavy 256-bit instructions. Thus there is no downclocking due to simdjson. + +For other reasons, you may still be worried about which SIMD instruction set is used by simdjson. Thankfully, [you can always determine and change which architecture-specific implementation is used](implementation-selection.md). Thus even if your CPU supports AVX2, you do not need to use AVX2. \ No newline at end of file