 |
Version 12.0.0
|
 | Data Structures | Source Location |
|---|---|---|
| |
Caution: the Architecture Guide is not updated in lockstep with the code base and is not necessarily correct or complete for any specific release.
After a Connection has been established between the application and WiredTiger, the application can start sending requests to WiredTiger using a session. A session is internally represented by WT_SESSION and plays an important role since almost all operations are performed under the context of a session.
A session can only be created through an existing connection with the API WT_CONNECTION::open_session and it is possible to create multiple sessions through the same connection. In fact, one connection can have multiple sessions but one session can only be associated with one connection. The maximum number of sessions is set through the configuration item session_max as part of the configuration string in wiredtiger_open.
Sessions created by the calling application are called "user sessions". WiredTiger also performs some internal operations such as Eviction through self-created sessions. These sessions are called "internal sessions". The usage rules and guidelines for both internal sessions and user sessions are the same and the only difference between them is their origin of creation.
The different operations that can be performed on a WiredTiger session are related to cursors, tables and transactions. You can read the complete description of each possible operation in the documentation related to WT_SESSION.
It is possible to group several operations within a session, in other words, multiple operations can be treated as a single atomic operation. This can be done using Transactions. Furthermore, a session can hold only one running transaction at any given time and this transaction only belongs to that session.
A session can perform multiple data operations on one or several collections using multiple cursors (see Cursor for more details). All the cursors associated with a session share that session transaction context. It is also possible to cache those cursors if required through the configuration string given to WT_CONNECTION::open_session or wiredtiger_open. The configuration item for this purpose is cache_cursors.
During its lifetime, a session can accumulate a list of data handles (see Data Handles). Indeed, when a session accesses a table for the first time, the data handle of that table is acquired and cached. Once a session no longer needs to operate on a table, it marks the associated data handle as idle. This helps the sweep server release data handles that are inactive, see Data Handles for more details.
A session can be closed using WT_SESSION::close. Closing the connection will also close all opened sessions. When a session is closed, it releases all the resources associated with it including rolling back any active transaction and closing the cursors that are still open.
A session is always executed as a single thread, see Multithreading for more details.
WT_SESSION::get_last_error can be used to provide more detailed information about the last session API call. The information includes an error code, a sub-level error code and message providing contextual information. The intended usage of the sub-level error code is to allow users to programmatically make decisions on the application level.
Internal to WiredTiger the WT_ERROR_INFO structure lives within the session object and tracks errors that occur during a session API call. The WT_SESSION::get_last_error will return back any information recorded within the WT_ERROR_INFO structure. An internal function set_last_error has been created and utilized throughout the code base to set any errors that may occur within WiredTiger.
There is an assumption made in the code base that an error returned with a sub-level error code or message will be not changed. Therefore when multiple errors happen within one session API call, the first error that returns with a sub-level error code or message will be returned to the user. In the case that none of the errors have a sub-level error code or message, the last error code is returned.
When saving an error, the session must have the WT_SESSION_SAVE_ERRORS flag set, or the error will not be saved. External sessions have this flag set while internal sessions do not. This is because internal sessions are not part of the session API and users do not have access to them. However, when an external session opens an internal session, it will inherit the external sessions flags including the WT_SESSION_SAVE_ERRORS flag. This allows any errors that occur to be saved within the internal session and propagate back to the external session, when the internal session is closed. This is required for only schema-type operations.
