doc/threading-warnings.txt

   1 ============= suggested addition to documentation ===============
   2 == Threads and thread safety
   3
   4 In a Lisp in which threading is internal, rather than done using OS threads, CLSQL should
   5 be threadsafe. Thus what follows will consider the case of Lisp threads also being OS
   6 threads.
   7
   8 CLSQL attempts to be thread-safe, with important exceptions.  The database pool used by
   9 CONNECT and WITH-DATABASE performs appropriate locking, so that
  10 it is possible to use pooled connections from different threads.   As long as database
  11 objects (representing connections) are not passed among threads, WITH-DATABASE
  12 and CONNECT may be used by multiple threads.
  13
  14 However, the database object contained in the VIEW-DATABASE slot of a STANDARD-DB-OBJECT
  15 persists even after the database is returned to the pool.  Thus it is possible for one
  16 thread to read an object, return the database to pool, and then still possess a copy of
  17 the database inside the   VIEW-DATABASE slot.    Then UPDATE-RECORDS-FOR-INSTANCE,
  18 UPDATE-RECORD-FROM-SLOT, and UPDATE-RECORD-FROM-SLOTS
  19 (which always use the VIEW-DATABASE slot, if not NIL, rather than any supplied
  20 keyword argument DATABASE) can use the database even as a second thread as
  21 retrieved it from a pool, resulting in serious problems.  Automatic updating using the internal
  22 VIEW-DATABASE slot also may be  triggered by the global variable *DB-AUTO-SYNC*.
  23
  24 This problem may been addressed by defining a new object class, and changing the method
  25 used to select the database during UPDATE-RECORDS-FOR-INSTANCE, etc.
  26
  27 ;; define a threadsafe child class of   STANDARD-DB-OBJECT
  28 (defclass clsql::threadsafe-db-obj (clsql-sys:standard-db-object) nil
  29   (:metaclass clsql-sys::standard-db-class))
  30
  31 ;; for this class, define threadsafe database chooser method that never uses the
  32 ;; internal VIEW-DATABASE slot
  33 (defmethod clsql-sys::choose-database-for-instance
  34     ((object clsql::threadsafe-db-obj) &optional database)
  35   (or database clsql-sys:*default-database*
  36         (signal-no-database-error nil)))
  37
  38 ;; define a new sql database table that should be threadsafely UPDATE-able
  39 (clsql-sys:def-view-class my-table  (clsql::threadsafe-db-obj)
  40     (…))
  41
  42
  43 Alternatively, users may redefine *DB-POOL* and *DB-POOL-LOCK* on a per-thread basis
  44 using LET before entering the thread, which will prevent any cross-thread sharing
  45 of connections, possibly at the cost of having more connections. [** is this a valid approach **]
  46 *DB-POOL-LOCK* no longer necessary, however, if connection pools are per-thread.
  47
  48
  49 ==== Thread safety issues for the back-ends [** my best understanding **]
  50
  51 * sqlite2 - sqlite2 is not threadsafe.
  52
  53 * sqlite3 - sqlite3 after and including 3.3.1 is threadsafe if compiled in the default manner.  According to sqlite3 documentation,
  54  connections may be moved across threads if and only if  no transaction is pending and all statements have been finalized.
  55
  56 * mysql - the mysql interface is missing initializations required for thread safety: 1) mysql_library_init() is not called in a multithreaded environment;
  57    2) mysql_thread_init() is not called on a per-thread basis; and 3) mysql_thread_end() is not called before a thread terminates.
  58      The second item may lead to corruption according to mysql documentation, and the third item
  59       leads to memory leaks.
  60
  61   Another issue with mysql is that it resets sigpipe in a way that renders SBCL unresponsive to interrupts, requiring additional saving and
  62   restoring of the signal handler.  [** an example? **]
  63
  64   Nevertheless, the present version of the mysql back end often works successfully even in a threaded environment, albeit with subtle problems.
  65
  66
  67 * postgreSQL - is probably threadsafe [No information]
  68
  69 * postgreSQL socket - Is probably threadsafe -- has been used for a while without any observed errors.
  70
  71 * ODBC - the Clsql side doesn't have additional issues beyond what's documented above. But this depends on what odbc driver your using. It appears to work with unixodbc and freetds.
  72
  73 * AODBC - no information
  74
  75 * Oracle  - no information
  76
  77 ============= end of suggested addition to documentation ===============