Artifact 6197f14c378fa96bfc6c9693a0f769ebf5e40e7e:
- File pages/threadsafe.in — part of check-in [d9e242f92a] at 2010-08-09 15:45:38 on branch trunk — Fix a bunch of documentation typos reported on the mailing list. (user: drh size: 3789)
<title>Using SQLite In Multi-Threaded Applications</title> <tcl>hd_keywords {threading mode}</tcl> <h2>SQLite And Multiple Threads</h2> <p>SQLite support three different threading modes:</p> <ol> <li><p><b>Single-thread</b>. In this mode, all mutexes are disabled and SQLite is unsafe to use in more than a single thread at once.</p></li> <li><p><b>Multi-thread</b>. In this mode, SQLite can be safely used by multiple threads provided that no single database connection is used simultaneously in two or more threads. </p></li> <li><p><b>Serialized</b>. In serialized mode, SQLite can be safely used by multiple threads with no restriction.</p></li> </ol> <p> The threading mode can be selected at compile-time (when the SQLite library is being compiled from source code) or at start-time (when the application that intends to use SQLite is initializing) or at run-time (when a new SQLite database connection is being created). Generally speaking, run-time overrides start-time and start-time overrides compile-time. Except, single-thread mode cannot be overridden once selected. </p> <p> The default mode is serialized. </p> <h3>Compile-time selection of threading mode</h3> <p> Use the [SQLITE_THREADSAFE] compile-time parameter to selected the threading mode. If no [SQLITE_THREADSAFE] compile-time parameter is present, then serialized mode is used. This can be made explicit with [SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=1]. With [SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=0] the threading mode is single-thread. With [SQLITE_THREADSAFE | -DSQLITE_THREADSAFE=2] the threading mode is multi-thread. </p> <p> The return value of the [sqlite3_threadsafe()] interface is determined by the compile-time threading mode selection. If single-thread mode is selected at compile-time, then [sqlite3_threadsafe()] returns false. If either the multi-thread or serialized modes are selected, then [sqlite3_threadsafe()] returns true. The [sqlite3_threadsafe()] interface predates the multi-thread mode and start-time and run-time mode selection and so is unable to distinguish between multi-thread and serialized mode nor is it able to report start-time or run-time mode changes. </p> <p> If single-thread mode is selected at compile-time, then critical mutexing logic is omitted from the build and it is impossible to enable either multi-thread or serialized modes at start-time or run-time. </p> <h3>Start-time selection of threading mode</h3> <p> Assuming that the compile-time threading mode is not single-thread, then the threading mode can be changed during initialization using the [sqlite3_config()] interface. The [SQLITE_CONFIG_SINGLETHREAD] verb puts SQLite into single-thread mode, the [SQLITE_CONFIG_MULTITHREAD] verb sets multi-thread mode, and the [SQLITE_CONFIG_SERIALIZED] verb sets serialized mode. </p> <h3>Run-time selection of threading mode</h3> <p>If single-thread mode has not been selected at compile-time or start-time, then individual database connections can be created as either multi-thread or serialized. It is not possible to downgrade an individual database connection to single-thread mode. Nor is it possible to escalate an individual database connection if the compile-time or start-time mode is single-thread.</p> <p>The threading mode for an individual database connection is determined by flags given as the third argument to [sqlite3_open_v2()]. The [SQLITE_OPEN_NOMUTEX] flag causes the database connection to be in the multi-thread mode and the [SQLITE_OPEN_FULLMUTEX] flag causes the connection to be in serialized mode. If neither flag is specified or if [sqlite3_open()] or [sqlite3_open16()] are used instead of [sqlite3_open_v2()], then the default mode determined by the compile-time and start-time settings is used. </p>