Some tweaks.

Daniel Lemire · Daniel Lemire · commit 23fbd9d00455 · 2020-06-14T18:28:09.000-04:00
diff --git 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
@@ -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
@@ -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.
