diff --git a/README.md b/README.md index fb79680..ebc92c3 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ with a few intuitive and well documented C++ class. - to keep dependencies to a minimum (STL and SQLite3) - to be portable - to be light and fast -- to be monothreaded (not thread-safe) +- to be thread-safe only as much as SQLite "Multi-thread" mode (see below) - to have a good unit test coverage - to use API names sticking with those of the SQLite library - to be well documented with Doxygen tags, and with some good examples @@ -58,6 +58,22 @@ And following IDEs/Compilers - the SQLite library, either by linking to it dynamicaly or staticaly (libsqlite3-dev under Linux), or by adding its source file in your project code base (source code provided in src/sqlite3 for Windows). +### Thread-safety + +SQLite supports three mode of thread safety, as describe in "SQLite And Multiple Threads" : +see http://www.sqlite.org/threadsafe.html + +This SQLiteC++ wrapper does no add any lock (no mutexes) nor any other thread-safety mecanism +above the SQLite library itself, by design, for lightness and speed. + +Thus, SQLiteC++ naturally supports the "Multi Thread" mode of SQLite ; +"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." + +But SQLiteC++ does not support the fully thread-safe "Serialized" mode of SQLite, +because of the way it shares the underling SQLite precompiled statement +in a custom shared pointer (See the inner class "Statement::Ptr"). + ### Installation: To use this wrappers, you need to add the 10 SQLiteC++ source files from the src/ directory diff --git a/src/Column.h b/src/Column.h index 9ac6579..cd9c220 100644 --- a/src/Column.h +++ b/src/Column.h @@ -36,6 +36,13 @@ namespace SQLite * * Its value can be expressed as a text, and, when applicable, as a numeric * (integer or floating point) or a binary blob. + * + * Thread-safety: a Column object shall not be shared by multiple threads, because : + * 1) in the SQLite "Thread Safe" mode, "SQLite can be safely used by multiple threads + * provided that no single database connection is used simultaneously in two or more threads." + * 2) the SQLite "Serialized" mode is not supported by SQLiteC++, + * because of the way it shares the underling SQLite precompiled statement + * in a custom shared pointer (See the inner class "Statement::Ptr"). */ class Column { diff --git a/src/Database.h b/src/Database.h index 293a9eb..c6451ec 100644 --- a/src/Database.h +++ b/src/Database.h @@ -28,6 +28,13 @@ namespace SQLite * Resource Acquisition Is Initialization (RAII) means that the Database Connection * is opened in the constructor and closed in the destructor, so that there is * no need to worry about memory management or the validity of the underlying SQLite Connection. + * + * Thread-safety: a Database object shall not be shared by multiple threads, because : + * 1) in the SQLite "Thread Safe" mode, "SQLite can be safely used by multiple threads + * provided that no single database connection is used simultaneously in two or more threads." + * 2) the SQLite "Serialized" mode is not supported by SQLiteC++, + * because of the way it shares the underling SQLite precompiled statement + * in a custom shared pointer (See the inner class "Statement::Ptr"). */ class Database { diff --git a/src/Statement.h b/src/Statement.h index d4a0ded..dd3f83b 100644 --- a/src/Statement.h +++ b/src/Statement.h @@ -31,6 +31,13 @@ class Column; * Resource Acquisition Is Initialization (RAII) means that the Statement * is compiled in the constructor and finalized in the destructor, so that there is * no need to worry about memory management or the validity of the underlying SQLite Statement. + * + * Thread-safety: a Statement object shall not be shared by multiple threads, because : + * 1) in the SQLite "Thread Safe" mode, "SQLite can be safely used by multiple threads + * provided that no single database connection is used simultaneously in two or more threads." + * 2) the SQLite "Serialized" mode is not supported by SQLiteC++, + * because of the way it shares the underling SQLite precompiled statement + * in a custom shared pointer (See the inner class "Statement::Ptr"). */ class Statement { diff --git a/src/Transaction.h b/src/Transaction.h index 85390d7..18d253b 100644 --- a/src/Transaction.h +++ b/src/Transaction.h @@ -30,6 +30,13 @@ class Database; * no need to worry about memory management or the validity of the underlying SQLite Connection. * * This method also offers big performances improvements compared to individually executed statements. + * + * Thread-safety: a Transaction object shall not be shared by multiple threads, because : + * 1) in the SQLite "Thread Safe" mode, "SQLite can be safely used by multiple threads + * provided that no single database connection is used simultaneously in two or more threads." + * 2) the SQLite "Serialized" mode is not supported by SQLiteC++, + * because of the way it shares the underling SQLite precompiled statement + * in a custom shared pointer (See the inner class "Statement::Ptr"). */ class Transaction {