diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contexts.md | 114 |
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 |