Import wiredtiger: 387b83a0394c004244383bea306bb4f3e641d249 from branch mongodb-master

ref: 38ddd74fc3..387b83a039
for: 5.1.0

WT-6913       file system and os interface architecture guide

5 files changed, 73 insertions, 13 deletions

diff --git a/src/third_party/wiredtiger/dist/docs_data.py b/src/third_party/wiredtiger/dist/docs_data.py
index 2d0ba1e6068..43554822cc3 100644
--- a/src/third_party/wiredtiger/dist/docs_data.py
+++ b/src/third_party/wiredtiger/dist/docs_data.py
@@ -52,11 +52,12 @@ arch_doc_pages = [
         ['src/include/cache.h',
          'src/evict/']),
     ArchDocPage('arch-fs-os',
-        ['WT_FILE_SYSTEM'],
+        ['WT_FILE_HANDLE', 'WT_FILE_SYSTEM'],
         ['src/include/os.h', 'src/include/os_fhandle_inline.h',
          'src/include/os_fs_inline.h', 'src/include/os_fstream_inline.h',
-         'src/include/os_windows.h',
-         'src/os_posix/', 'src/os_win/']),
+         'src/include/os_windows.h', 'src/include/posix.h',
+         'src/os_common/', 'src/os_posix/', 'src/os_win/',
+         ]),
     ArchDocPage('arch-hs',
         ['WT_CURSOR_HS'],
         ['src/history/']),
diff --git a/src/third_party/wiredtiger/examples/c/ex_file_system.c b/src/third_party/wiredtiger/examples/c/ex_file_system.c
index ad43cfe1cc0..9df1f6d73ca 100644
--- a/src/third_party/wiredtiger/examples/c/ex_file_system.c
+++ b/src/third_party/wiredtiger/examples/c/ex_file_system.c
@@ -228,7 +228,7 @@ demo_file_system_create(WT_CONNECTION *conn, WT_CONFIG_ARG *config)
     }
 
     allocate_file_system_lock(&demo_fs->lock);
-
+    /*! [WT_FILE_SYSTEM create] */
     /* Initialize the in-memory jump table. */
     file_system->fs_directory_list = demo_fs_directory_list;
     file_system->fs_directory_list_free = demo_fs_directory_list_free;
@@ -244,6 +244,7 @@ demo_file_system_create(WT_CONNECTION *conn, WT_CONFIG_ARG *config)
           wtext, NULL, "WT_CONNECTION.set_file_system: %s", wtext->strerror(wtext, NULL, ret));
         goto err;
     }
+    /*! [WT_FILE_SYSTEM create] */
     return (0);
 
 err:
@@ -320,7 +321,7 @@ demo_fs_open(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name,
         ret = ENOMEM;
         goto err;
     }
-
+    /*! [WT_FILE_HANDLE create] */
     /*
      * Setup the function call table for our custom file system. Set the function pointer to NULL
      * where our implementation doesn't support the functionality.
@@ -345,6 +346,7 @@ demo_fs_open(WT_FILE_SYSTEM *file_system, WT_SESSION *session, const char *name,
     ++demo_fs->opened_unique_file_count;
 
     *file_handlep = file_handle;
+    /*! [WT_FILE_HANDLE create] */
 
     if (0) {
 err:
diff --git a/src/third_party/wiredtiger/import.data b/src/third_party/wiredtiger/import.data
index 910c15de59b..72a90223e13 100644
--- a/src/third_party/wiredtiger/import.data
+++ b/src/third_party/wiredtiger/import.data
@@ -2,5 +2,5 @@
     "vendor": "wiredtiger",
     "github": "wiredtiger/wiredtiger.git",
     "branch": "mongodb-master",
-    "commit": "38ddd74fc34c2603fd350c2175611241f5171ec4"
+    "commit": "387b83a0394c004244383bea306bb4f3e641d249"
 }
diff --git a/src/third_party/wiredtiger/src/docs/arch-fs-os.dox b/src/third_party/wiredtiger/src/docs/arch-fs-os.dox
index cedade13248..e9e71dc9f14 100644
--- a/src/third_party/wiredtiger/src/docs/arch-fs-os.dox
+++ b/src/third_party/wiredtiger/src/docs/arch-fs-os.dox
@@ -1,10 +1,61 @@
-/*! @arch_page arch-fs-os File System and Operating System Interface
+/*! @arch_page arch-fs-os File System Interface and Operating System Support
 
-Internally, a layer of abstraction is above all operating system calls,
-allowing main line WiredTiger code to make a call to single set of interfaces.
-There are currently OS specific APIs for POSIX and Windows.
+@section multiple_os Support for Multiple Operating Systems
+WiredTiger runs on a variety of systems with different interfaces for file system
+and operating system services. Therefore we have abstract implementations of various
+OS services, such as threading, clock, etc. We choose which implementation of the
+abstraction to include at compile time, and the rest of WT code doesn't need to worry
+about these details. Currently WiredTiger supports POSIX and Windows operating systems
+through maintaining separate folders for each system. By checking the current machine's
+operating system, WiredTiger either compiles the \c os_posix or \c os_win folder.
+Additional structures and definitions specific to the operating system are defined
+in the header files \c posix.h or \c os_windows.h.
 
-Additionally, a program can use WT_CONNECTION::set_file_system to register
-a set of functions that will be called for each file system operation.
-WiredTiger will then call these functions at the appropriate time.
+@section file_system_and_handle WiredTiger File System and File Handle Interfaces
+WiredTiger provides file system and file handle abstraction layers, or interfaces,
+to accommodate for a standard set of functionalities across multiple file systems
+that may not have identical features.
+
+@subsection file_system File System Interface
+The file system interface handles system calls on the file system namespace such
+as creation and deletion. WiredTiger defines the file system interface through
+\c WT_FILE_SYSTEM, which is initialized when a WiredTiger connection is opened. The
+interface has a set of function pointers that represent the file system functionalities
+that WiredTiger supports for a directory. WiredTiger defines POSIX and Windows file
+system function implementations in \c os_fs.c.
+
+@subsection file_handle File Handle Interface
+WiredTiger has a file handle interface called WT_FILE_HANDLE which defines a
+set of function pointers that represent I/O operations for a file. We use this
+interface as a base class to create file handle implementations specific to the
+operating system, for example \c WT_FILE_HANDLE_POSIX or \c WT_FILE_HANDLE_WINDOWS.
+These WiredTiger file handle structures are initialized when WT_FILE_SYSTEM::fs_open_file
+is called.
+
+In WiredTiger, whenever a file is opened a file handle is created to accommodate
+the state of the file in cache. To prevent multiple file handles being created for a
+file, WiredTiger uses a hash table to maintain an single file handle for each opened
+file. A structure called \c WT_FH is used for accessing each entry in the hash table.
+Thus WiredTiger checks the hash table via \c WT_FH for an open file handle.
+
+@subsection file_customization File System and Handle Customization
+WiredTiger provides an API that allows programs to register their own customized file
+system using the WT_CONNECTION::set_file_system function. Programs need to supply
+their own file system structure and file handle implementations. See @ref custom_file_systems
+for an example of how file system and handles are customized.
+
+@subsection file_in_memory In-memory support
+The in-memory configuration changes WiredTiger to run only in cache with no disk writes
+and is enabled through the WiredTiger connection configuration string. WiredTiger maintains
+each file through providing an in memory buffer for each file handle. Both in-memory file
+system and file handle implementations are found in \c os_fs_inmemory.c.
+
+@subsection file_stream File Stream
+WiredTiger contains a file stream implementation called \c WT_FSTREAM. This structure
+is mainly used for non-critical functionalities such as writing verbose messages or
+writing to WiredTiger statistics logs.
+
+@section filesystem_usage Multiple System Architecture Support
+WiredTiger supports x86_64, i386, mips, ppc, aarch64, s390x, and sparc system architectures
+which are found in gcc.h.
 */
diff --git a/src/third_party/wiredtiger/src/docs/spell.ok b/src/third_party/wiredtiger/src/docs/spell.ok
index 19fa479cd0b..fbe9305e6f6 100644
--- a/src/third_party/wiredtiger/src/docs/spell.ok
+++ b/src/third_party/wiredtiger/src/docs/spell.ok
@@ -56,6 +56,7 @@ Facebook's
 FlameGraph
 FlameGraphs
 FlexeLint
+FSTREAM
 FreeBSD
 FreeBSD's
 GCC
@@ -151,6 +152,7 @@ XRay
 Yann
 Za
 Zstd
+aarch
 aR
 abc
 abstime
@@ -372,6 +374,7 @@ iflag
 incr
 indices
 init
+inmemory
 insn
 intl
 intpack
@@ -443,6 +446,7 @@ memp
 metadata
 metatracking
 minkey
+mips
 mispredictions
 mixin
 mixins
@@ -511,6 +515,7 @@ pid
 plantuml
 png
 posix
+ppc
 pre
 prealloc
 prepended
@@ -584,6 +589,7 @@ skinparam
 skiplist
 skiplists
 sortable
+sparc
 spinlock
 spinlocks
 sql