1 files changed, 37 insertions, 0 deletions
diff --git a/docs/src/threads.dox b/docs/src/threads.dox
new file mode 100644
index 00000000000..36c7a2c7f0c
--- /dev/null
+++ b/docs/src/threads.dox
@@ -0,0 +1,37 @@
+/*! @page threads Multithreading
+
+WT_CONNECTION handles can be shared between threads, and applications
+generally only open one connection to a given database per process. All
+methods on WT_CONNECTION are thread safe.
+
+WT_SESSION and WT_CURSOR handles cannot be shared between threads concurrently:
+the usual approach is for applications to open one WT_SESSION for each thread
+that accesses a database.  Applications may open multiple WT_CURSOR handles
+within a session.
+
+Multiple threads must not access a session handle concurrently (including
+accessing two or more cursor handles in the same session).  However,
+WT_SESSION handles may be accessed by different threads serially (for
+example, from a pool of threads managed by the application with a set of
+shared session handles).  There is no thread-local state in WiredTiger, but
+no built-in synchronization of session state either, so if multiple threads
+access a session handle or dependencies such as cursors, the access must be
+serialized by the application.
+
+@section threads_example Code samples
+
+The code below is taken from the complete example program
+@ex_ref{ex_thread.c}.
+
+This is an example of a thread entry point.  A new session is opened for
+the thread and used for all operations within that thread.
+
+@snippet ex_thread.c thread scan
+
+Here is the main function that starts the threads.  It opens a single
+connection, shared between the threads, and closes the connection after
+waiting for all of the threads to exit.
+
+@snippet ex_thread.c thread main
+
+ */