SERVER-48718: Document server contextual singletons

1 files changed, 114 insertions, 0 deletions

diff --git a/docs/contexts.md b/docs/contexts.md
new file mode 100644
index 00000000000..a1397b8bf63
--- /dev/null
+++ b/docs/contexts.md
@@ -0,0 +1,114 @@
+# Contextual Singletons
+
+The state of all operations performed on Mongo server processes (i.e., `mongod` and `mongos`) is
+tracked and managed by a global singleton called the `ServiceContext`. A `ServiceContext` maintains
+an arbitrary number of `Client` objects, which each represent a _logical_ connection to the database
+over which operations can be performed. Each operation in turn is managed by a single
+`OperationContext`. A `Client` object can only perform a single logical operation at a time, and
+thus can only maintain a single `OperationContext` at a time. Note that all of these classes are
+heavily _decorated_ (i.e., they inherit from [`Decorable`][decorable-url]), which makes them
+dynamically extensible.
+
+## [`ServiceContext`][service-context-url]
+
+A `ServiceContext` represents all of the state of a single Mongo server process, which may be either
+a `mongod` or a `mongos`. It creates and manages the previously mentioned `Client`s and
+`OperationContext`s, as well as a `TransportLayer` for performing network operations, a
+`PeriodicRunner` for running housekeeping tasks periodically, a `StorageEngine` for interacting
+with the actual database itself, and a set of time sources. In general, every Mongo server process
+has a single `ServiceContext`, known as the _global_ `ServiceContext`. Typical uses of the global
+`ServiceContext` outside of server initialization and shutdown include looking up `Client` or
+`OperationContext` information for a particular thread or operation, or killing one or more running
+operations during, e.g., a primary replica step-down. The global `ServiceContext` is created during
+initialization of a Mongo server process and is only destroyed at shutdown, and is thus available
+for the entire duration of server operation. At shutdown, the global `ServiceContext` will kill all
+outstanding `OperationContext`s and `Client`s.
+
+The `ServiceContext` associated with a given `Client` object can be fetched in a few ways; prefer
+using [`Client::getServiceContext()`][client-get-service-context-url] when possible. As of time of
+writing, every server process only maintains a single `ServiceContext`, but preferring
+`Client::getServiceContext()` or `ServiceContext::getCurrentServiceContext()` over
+[`ServiceContext::getGlobalServiceContext()`][get-global-service-context-url] will allow us to
+more easily maintain multiple `ServiceContext`s per server process if desired in the future.
+
+## [`Client`][client-url]
+
+Each logical connection to a Mongo service is managed by a `Client` object, where a logical
+connection may be a user or an internal process that needs to run a command or query on the database.
+Construction of a `Client` object is typically performed with a call to `makeClient` on the global
+`ServiceContext`, which can then be attached to any thread of execution, or with a call to
+[`Client::initThread`][client-init-thread-url] which constructs a `Client` on the global
+`ServiceContext` and binds it to the current thread. All operations executed by the `Client` will
+take place on that `Client`’s associated thread serially over the network connection managed by the
+`Session` object that was passed into the `Client`’s constructor. If no `Session` is passed to the
+`Client`’s constructor, then the `Client` is assumed to operate on a local database and will perform
+no network operations. These `Client`s are sometimes referred to as “local clients”, and are often
+used when a Mongo service needs to query its own database.
+
+A `Client` will typically execute multiple operations over the course of its lifetime, spawning an
+`OperationContext` for each. Because these operations are executed serially, each `Client` is
+associated with up to one `OperationContext` at any given time.
+
+### The `Client` lock
+
+All `Client`s have an associated lock which protects their internal state including their currently
+associated `OperationContext` from concurrent access. Any mutation to a `Client`’s associated
+`OperationContext` (or other protected internal state) _must_ take the `Client` lock before being
+performed, as an `OperationContext` can otherwise be killed and destroyed at any time. A `Client`
+thread may read its own internal state  without taking the `Client` lock, but _must_ take the
+`Client` lock when reading another `Client` thread's internal state. Only a `Client`'s owning thread
+may write to its `Client`'s internal state, and must take the lock when doing so. `Client`s
+implement the standard lockable interface (`lock()`, `unlock()`, and `try_lock()`) to support these
+operations. The semantics of the `Client` lock are summarized in the table below.
+
+| Internal state | `Client`-owning thread | Other threads |
+| -------------- | ---------------------- | ------------- |
+| reads          | always allowed         | lock required |
+| writes         | lock required          | never allowed |
+
+### `Client` thread manipulation
+
+ [`Client::cc()`][client-cc-url] may be used to get the `Client` object associated with the currently
+executing thread. Prefer passing `Client` objects as parameters over calls to `Client::cc()` when
+possible. A [`ThreadClient`][thread-client-url] is an RAII-style class which may be used to construct
+and bind a `Client` to the current running thread and automatically unbind it once the `ThreadClient`
+goes out of scope. An [`AlternativeClientRegion`][acr-url] is another RAII-style class which may be
+used to temporarily bind a `Client` object to the currently running thread (holding any currently
+bound `Client` in reserve), rebinding the current thread’s old `Client` to the current thread upon
+falling out of scope. [`ClientStrand`][client-strand-url] functions similarly, but also provides an
+`Executor` interface for binding a `Client` to an arbitrary thread.
+
+## [`OperationContext`][operation-context-url]
+
+Each operation that executes on a Mongo server (e.g., a query or a command) is managed by its own
+`OperationContext`. An `OperationContext` shepherds an operation’s execution from its inception to
+either completion or cancellation. Cancellation may be triggered externally, such as from the
+controlling `ServiceContext` on a primary step-down, or from a user-issued [`killOp`][kill-op-url]
+command; or internally, e.g., when an operation’s deadline has expired. Every `OperationContext` is
+associated with a single `Client`, which manages the logical connection to the database over which
+the operation will actually be executed. `OperationContext`s are also optionally associated with a
+[`Baton`][baton-url], which represents a thread of execution on which networking operations can be
+performed asynchronously.
+
+### Interruptibility
+
+`OperationContext`s implement the [`Interruptible`][interruptible-url] interface, which allows them to
+be killed by their associated `Client`s (or, by proxy, their owning `ServiceContext`). See
+[this comment block][opctx-interruptible-comment-block-url] for more details on when and how
+`OperationContext`s are interrupted.
+
+[service-context-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/service_context.h#L141
+[decorable-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/util/decorable.h
+[client-get-service-context-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h#L117
+[get-global-service-context-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/service_context.h#L755
+[client-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h
+[client-init-thread-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h#L75
+[client-cc-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h#L372
+[thread-client-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h#L320
+[acr-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client.h#L347
+[client-strand-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/client_strand.h
+[operation-context-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/operation_context.h
+[kill-op-url]: https://docs.mongodb.com/manual/reference/command/killOp/
+[baton-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/baton.h
+[interruptible-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/util/interruptible.h
+[opctx-interruptible-comment-block-url]: https://github.com/mongodb/mongo/blob/ecc6179c18ed1e3b38d7ee244319210b18e24bad/src/mongo/db/operation_context.cpp#L281