** This file contains the C functions that implement mutexes for
** use by the SQLite core.
**
-** $Id: mutex.c,v 1.11 2007/08/25 14:39:46 drh Exp $
+** $Id: mutex.c,v 1.12 2007/08/25 16:21:30 drh Exp $
*/
/*
** If SQLITE_MUTEX_APPDEF is defined, then this whole module is
#ifndef SQLITE_MUTEX_APPDEF
-/* This is the beginning of real code
+/* This is the beginning of internal implementation of mutexes
+** for SQLite.
*/
#include "sqliteInt.h"
/*
-** Figure out what version of the code to use
+** Figure out what version of the code to use. The choices are
+**
+** SQLITE_MUTEX_NOOP For single-threaded applications that
+** do not desire error checking.
+**
+** SQLITE_MUTEX_NOOP_DEBUG For single-threaded applications with
+** error checking to help verify that mutexes
+** are being used correctly even though they
+** are not needed. Used when SQLITE_DEBUG is
+** defined on single-threaded builds.
+**
+** SQLITE_MUTEX_PTHREADS For multi-threaded applications on Unix.
+**
+** SQLITE_MUTEX_WIN For multi-threaded applications on Win32.
*/
#define SQLITE_MUTEX_NOOP 1 /* The default */
#if defined(SQLITE_DEBUG) && !SQLITE_THREADSAFE
** The mutex object
*/
struct sqlite3_mutex {
- int id;
- int cnt;
+ int id; /* The mutex type */
+ int cnt; /* Number of entries without a matching leave */
};
/*
*/
void sqlite3_mutex_enter(sqlite3_mutex *p){
assert( p );
- assert( p->cnt==0 || p->id==SQLITE_MUTEX_RECURSIVE );
+ assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
p->cnt++;
}
int sqlite3_mutex_try(sqlite3_mutex *p){
assert( p );
- if( p->cnt>0 && p->id!=SQLITE_MUTEX_RECURSIVE ){
- return SQLITE_BUSY;
- }
+ assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
p->cnt++;
return SQLITE_OK;
}
** is not currently allocated. SQLite will never do either.
*/
void sqlite3_mutex_leave(sqlite3_mutex *p){
- assert( p->cnt>0 );
+ assert( p );
+ assert( sqlite3_mutex_held(p) );
p->cnt--;
+ assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
}
/*
assert( p );
assert( sqlite3_mutex_held(p) );
p->nRef--;
+ assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
pthread_mutex_unlock(&p->mutex);
}
/*
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
-** intended for use inside assert() statements.
+** intended for use only inside assert() statements. On some platforms,
+** there might be race conditions that can cause these routines to
+** deliver incorrect results. In particular, if pthread_equal() is
+** not an atomic operation, then these routines might delivery
+** incorrect results. On most platforms, pthread_equal() is a
+** comparison of two integers and is therefore atomic. But we are
+** told that HPUX is not such a platform. If so, then these routines
+** will not always work correctly on HPUX.
+**
+** On those platforms where pthread_equal() is not atomic, SQLite
+** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
+** make sure no assert() statements are evaluated and hence these
+** routines are never called.
*/
+#ifndef NDEBUG
int sqlite3_mutex_held(sqlite3_mutex *p){
return p==0 || (p->nRef!=0 && pthread_equal(p->owner, pthread_self()));
}
int sqlite3_mutex_notheld(sqlite3_mutex *p){
return p==0 || p->nRef==0 || pthread_equal(p->owner, pthread_self())==0;
}
+#endif
#endif /* SQLITE_MUTEX_PTHREAD */
#ifdef SQLITE_MUTEX_WIN
assert( p->nRef>0 );
assert( p->owner==GetCurrentThreadId() );
p->nRef--;
+ assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
LeaveCriticalSection(&p->mutex);
}
/*
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
-** intended for use inside assert() statements.
+** intended for use only inside assert() statements.
*/
int sqlite3_mutex_held(sqlite3_mutex *p){
return p==0 || (p->nRef!=0 && p->owner==GetCurrentThreadId());
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
-** @(#) $Id: sqlite.h.in,v 1.241 2007/08/25 14:49:37 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.242 2007/08/25 16:21:30 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
**
** Each open SQLite database is represented by pointer to an instance of the
** opaque structure named "sqlite3". It is useful to think of an sqlite3
-** pointer as an object. The [sqlite3_open], [sqlite3_open16], and
-** [sqlite3_open_v2] interfaces are its constructors
-** and [sqlite3_close] is its destructor. There are many other interfaces
-** (such as [sqlite3_prepare_v2], [sqlite3_create_function], and
-** [sqlite3_busy_timeout] to name but three) that are methods on this
+** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
+** [sqlite3_open_v2()] interfaces are its constructors
+** and [sqlite3_close()] is its destructor. There are many other interfaces
+** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
+** [sqlite3_busy_timeout()] to name but three) that are methods on this
** object.
*/
typedef struct sqlite3 sqlite3;
**
** As an example, suppose the query result where this table:
**
-** <pre>
+** <blockquote><pre>
** Name | Age
** -----------------------
** Alice | 43
** Bob | 28
** Cindy | 21
-** </pre>
+** </pre></blockquote>
**
** If the 3rd argument were &azResult then after the function returns
** azResult will contain the following data:
**
-** <pre>
-** azResult[0] = "Name";
-** azResult[1] = "Age";
-** azResult[2] = "Alice";
-** azResult[3] = "43";
-** azResult[4] = "Bob";
-** azResult[5] = "28";
-** azResult[6] = "Cindy";
-** azResult[7] = "21";
-** </pre>
+** <blockquote><pre>
+** azResult[0] = "Name";
+** azResult[1] = "Age";
+** azResult[2] = "Alice";
+** azResult[3] = "43";
+** azResult[4] = "Bob";
+** azResult[5] = "28";
+** azResult[6] = "Cindy";
+** azResult[7] = "21";
+** </pre></blockquote>
**
** Notice that there is an extra row of data containing the column
** headers. But the *nrow return value is still 3. *ncolumn is
** CAPI3REF: Memory Allocation Subsystem
**
** The SQLite core uses these three routines for all of its own
-** internal memory allocation needs. The default implementation
+** internal memory allocation needs. The default implementation
** of the memory allocation subsystem uses the malloc(), realloc()
** and free() provided by the standard C library. However, if
** SQLite is compiled with the following C preprocessor macro
**
** then no implementation is provided for these routines by
** SQLite. The application that links against SQLite is
-** expected to provide its own implementation.
+** expected to provide its own implementation. If the application
+** does provide its own implementation for these routines, then
+** it must also provide an implementation for
+** [sqlite3_memory_alarm()].
+**
+** <b>Exception:</b> The windows OS interface layer calls
+** the system malloc() and free() directly when converting
+** filenames between the UTF-8 encoding used by SQLite
+** and whatever filename encoding is used by the particular windows
+** installation. Memory allocation errors are detected, but
+** they are reported back as [SQLITE_CANTOPEN] or
+** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
*/
void *sqlite3_malloc(int);
void *sqlite3_realloc(void*, int);
** [sqlite3_release_memory()] in the alarm callback. Application
** programs should not attempt to use the [sqlite3_memory_alarm()]
** interface because doing so will interfere with the
-** [sqlite3_soft_heap_limit()] module.
+** [sqlite3_soft_heap_limit()] module. This interface is exposed
+** only so that applications can provide their own
+** alternative implementation when the SQLite core is
+** compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
*/
int sqlite3_memory_alarm(
void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
** numbering and the value returned by this interface is the index of the
** host parameter with the largest index value.
**
-** The prepared statement must not not be [sqlite3_finalize | finalized]
+** The prepared statement must not be [sqlite3_finalize | finalized]
** prior to this routine returnning. Otherwise the results are undefined
** and probably undesirable.
*/
**
** <blockquote>
** <table border="1">
-** <tr><th> Internal <th> Requested <th>
-** <tr><th> Type <th> Type <th> Conversion
+** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
**
** <tr><td> NULL <td> INTEGER <td> Result is 0
** <tr><td> NULL <td> FLOAT <td> Result is 0.0
** millisecond time resolution, then the time will be rounded up to
** the nearest second. The number of milliseconds of sleep actually
** requested from the operating system is returned.
+**
+** SQLite implements this interface by calling the xSleep()
+** method of the default [sqlite3_vfs] object.
*/
int sqlite3_sleep(int);
** Prior to SQLite version 3.5.0, this routine only constrained the memory
** allocated by a single thread - the same thread in which this routine
** runs. Beginning with SQLite version 3.5.0, the soft heap limit is
-** applied cumulatively to all threads.
+** applied to all threads. The value specified for the soft heap limit
+** is an bound on the total memory allocation for all threads. In
+** version 3.5.0 there is no mechanism for limiting the heap usage for
+** individual threads.
*/
void sqlite3_soft_heap_limit(int);
** permitted to use any of these routines.
**
** The SQLite source code contains multiple implementations
-** of these mutex routines that can be selected at compile-time
-** by defining one of the following C preprocessor macros:
+** of these mutex routines. An appropriate implementation
+** is selected automatically at compile-time. The following
+** implementations are available in the SQLite core:
**
** <ul>
** <li> SQLITE_MUTEX_PTHREAD
-** <li> SQLITE_MUTEX_WIN32
+** <li> SQLITE_MUTEX_WIN
** <li> SQLITE_MUTEX_NOOP
-** <li> SQLITE_MUTEX_APPDEF
** </ul>
**
-** If none of the above macros is defined, the code uses
-** a default implementation.
-**
** The SQLITE_MUTEX_NOOP implementation is a set of routines
** that does no real locking and is appropriate for use in
-** a single-threaded application.
+** a single-threaded application. The SQLITE_MUTEX_PTHREAD
+** and SQLITE_MUTEX_WIN implementations are appropriate for
+** use on unix and windows.
**
-** If the SQLITE_MUTEX_APPDEF is defined, then no mutex
+** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
+** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
** implementation is included with the library. The
-** mutex interface routines defined above are external
+** mutex interface routines defined here become external
** references in the SQLite library for which implementations
-** must be provided by the application.
+** must be provided by the application. This facility allows an
+** application that links against SQLite to provide its own mutex
+** implementation without having to modify the SQLite core.
**
** The sqlite3_mutex_alloc() routine allocates a new
** mutex and returns a pointer to it. If it returns NULL
** might return such a mutex in response to SQLITE_MUTEX_FAST.
**
** The other allowed parameters to sqlite3_mutex_alloc() each return
-** a pointer to a static preexisting mutex. Three static mutexes are
+** a pointer to a static preexisting mutex. Four static mutexes are
** used by the current version of SQLite. Future versions of SQLite
** may add additional static mutexes. Static mutexes are for internal
** use by SQLite only. Applications that use SQLite mutexes should
** more than once, the behavior is undefined. SQLite will never exhibit
** such behavior in its own use of mutexes.
**
-** The sqlite3_mutex_exit() routine exits a mutex that was
+** The sqlite3_mutex_leave() routine exits a mutex that was
** previously entered by the same thread. The behavior
-** is undefined if the mutex is not currently entered or
-** is not currently allocated. SQLite will never do either.
+** is undefined if the mutex is not currently entered by the
+** calling thread or is not currently allocated. SQLite will
+** never do either.
+**
+** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
+*/
+sqlite3_mutex *sqlite3_mutex_alloc(int);
+void sqlite3_mutex_free(sqlite3_mutex*);
+void sqlite3_mutex_enter(sqlite3_mutex*);
+int sqlite3_mutex_try(sqlite3_mutex*);
+void sqlite3_mutex_leave(sqlite3_mutex*);
+
+/*
+** CAPI3REF: Mutex Verifcation Routines
**
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
** are intended for use inside assert() statements. The SQLite core
** never uses these routines except inside an assert() and applications
-** are advised to follow the lead of the core. These routines should
-** return true if the mutex in their argument is held or not held,
-** respectively, by the current thread. The implementation is
-** not required to provided working implementations of these
-** routines as their intended use is within assert() statements
-** only. If the implementation does not provide working
-** versions of these routines, it must at least provide stubs
-** that always return true.
+** are advised to follow the lead of the core. The core only
+** provides implementations for these routines when it is compiled
+** with the SQLITE_DEBUG flag. External mutex implementations
+** are only required to provide these routines if SQLITE_DEBUG is
+** defined and if NDEBUG is not defined.
+**
+** These routines should return true if the mutex in their argument
+** is held or not held, respectively, by the calling thread.
+**
+** The implementation is not required to provided versions of these
+** routines that actually work.
+** If the implementation does not provide working
+** versions of these routines, it should at least provide stubs
+** that always return true so that one does not get spurious
+** assertion failures.
**
** If the argument to sqlite3_mutex_held() is a NULL pointer then
** the routine should return 1. This seems counter-intuitive since
** the appropriate thing to do. The sqlite3_mutex_notheld()
** interface should also return 1 when given a NULL pointer.
*/
-sqlite3_mutex *sqlite3_mutex_alloc(int);
-void sqlite3_mutex_free(sqlite3_mutex*);
-void sqlite3_mutex_enter(sqlite3_mutex*);
-int sqlite3_mutex_try(sqlite3_mutex*);
-void sqlite3_mutex_leave(sqlite3_mutex*);
int sqlite3_mutex_held(sqlite3_mutex*);
int sqlite3_mutex_notheld(sqlite3_mutex*);
projects / thirdparty / sqlite.git / commitdiff
