Lock a FILE once per parse instead of once per character

Parsing from a FILE* reads one character at a time with std::fgetc, which
locks and unlocks the FILE object for every character. file_input_adapter
now locks the file once when it is created and unlocks it when it is
destroyed - also when parsing throws - and reads with the unlocked stdio
functions in between: flockfile/getc_unlocked/funlockfile with glibc,
Apple, Android, and the BSDs, and _lock_file/_fgetc_nolock/_unlock_file
with the Microsoft C runtime. Other C libraries keep std::fgetc. The lock
is recursive, so fread() in the binary readers and stdio calls of a SAX
handler or parser callback on the same thread keep working.

On an Apple M1 Max, parsing from a FILE* is 2.9 to 4.0 times as fast
(twitter.json 14.3 -> 4.1 ms, citm_catalog.json 35.4 -> 8.8 ms); with
glibc, whose locking is cheaper, 1.1 to 1.3 times. The values and the
position of the file after parsing are unchanged.

Other threads that use the same FILE object now wait until parsing is
done instead of interleaving their reads with the parser's.
JSON_DISABLE_UNLOCKED_FILE_IO restores std::fgetc, for programs in which a
SAX handler waits for another thread that uses the same FILE. The new
tests check from a second thread that the lock is released after success
and after a parse error, and run again with the macro.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/accept.md

@@ -134,6 +134,8 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
   instead of treating it as end of input
 - [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
   at a time
+- [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
+  functions
 
 ## Version history
 
@@ -147,6 +149,8 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
   it as end of input; planned to become the default in version 4.0.0.
 - Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0
   ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
+- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
+  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/parse.md

@@ -116,9 +116,11 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
 
     Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A
     `#!cpp std::istream` comes close: the parser scans the characters its stream buffer holds in bulk, without reading
-    ahead, so the stream is left exactly where it would be after reading one character at a time. See
-    [input sources and performance](../../features/parsing/index.md#input-sources-and-performance) and
-    [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md).
+    ahead, so the stream is left exactly where it would be after reading one character at a time. A `#!cpp FILE*` is
+    read one character at a time, but the file is locked only once, so other threads that use the same `FILE` object
+    wait until parsing is done. See [input sources and performance](../../features/parsing/index.md#input-sources-and-performance),
+    [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md), and
+    [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md).
 
 ## Examples
 
@@ -257,6 +259,8 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
   instead of treating it as end of input
 - [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
   at a time
+- [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
+  functions
 
 ## Version history
 
@@ -274,6 +278,8 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
 - Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0
   ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) restores reading one character at a
   time).
+- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
+  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) restores `std::fgetc`).
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -116,6 +116,10 @@ consumer `sax` has a super-linear complexity.
 
 A UTF-8 byte order mark is silently ignored.
 
+When reading from a `#!c FILE*`, the file is locked while it is parsed. The lock is recursive, so the SAX handler may
+use the same file with stdio functions, but it must not wait for another thread that uses the same `FILE` object; see
+[`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md).
+
 ## Examples
 
 ??? example
@@ -139,6 +143,8 @@ A UTF-8 byte order mark is silently ignored.
 - [accept](accept.md) - check if the input is valid JSON
 - [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
   at a time
+- [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
+  functions
 
 ## Version history
 
@@ -152,6 +158,8 @@ A UTF-8 byte order mark is silently ignored.
   after the parsed value when `strict` is `#!cpp false`.
 - Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0
   ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
+- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
+  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).
 
 !!! warning "Deprecation"