221 lines
8.4 KiB
HTML
221 lines
8.4 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html><head>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
||
|
|
<link href="../sqlite.css" rel="stylesheet">
|
||
|
|
<title>Mutexes</title>
|
||
|
|
<!-- path=../ -->
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class=nosearch>
|
||
|
|
<a href="../index.html">
|
||
|
|
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
|
||
|
|
</a>
|
||
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
||
|
|
<div class="tagline desktoponly">
|
||
|
|
Small. Fast. Reliable.<br>Choose any three.
|
||
|
|
</div>
|
||
|
|
<div class="menu mainmenu">
|
||
|
|
<ul>
|
||
|
|
<li><a href="../index.html">Home</a>
|
||
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
||
|
|
<li class='wideonly'><a href='../about.html'>About</a>
|
||
|
|
<li class='desktoponly'><a href="../docs.html">Documentation</a>
|
||
|
|
<li class='desktoponly'><a href="../download.html">Download</a>
|
||
|
|
<li class='wideonly'><a href='../copyright.html'>License</a>
|
||
|
|
<li class='desktoponly'><a href="../support.html">Support</a>
|
||
|
|
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
|
||
|
|
<li class='search' id='search_menubutton'>
|
||
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="menu submenu" id="submenu">
|
||
|
|
<ul>
|
||
|
|
<li><a href='../about.html'>About</a>
|
||
|
|
<li><a href='../docs.html'>Documentation</a>
|
||
|
|
<li><a href='../download.html'>Download</a>
|
||
|
|
<li><a href='../support.html'>Support</a>
|
||
|
|
<li><a href='../prosupport.html'>Purchase</a>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="searchmenu" id="searchmenu">
|
||
|
|
<form method="GET" action="../search">
|
||
|
|
<select name="s" id="searchtype">
|
||
|
|
<option value="d">Search Documentation</option>
|
||
|
|
<option value="c">Search Changelog</option>
|
||
|
|
</select>
|
||
|
|
<input type="text" name="q" id="searchbox" value="">
|
||
|
|
<input type="submit" value="Go">
|
||
|
|
</form>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script>
|
||
|
|
function toggle_div(nm) {
|
||
|
|
var w = document.getElementById(nm);
|
||
|
|
if( w.style.display=="block" ){
|
||
|
|
w.style.display = "none";
|
||
|
|
}else{
|
||
|
|
w.style.display = "block";
|
||
|
|
}
|
||
|
|
}
|
||
|
|
function toggle_search() {
|
||
|
|
var w = document.getElementById("searchmenu");
|
||
|
|
if( w.style.display=="block" ){
|
||
|
|
w.style.display = "none";
|
||
|
|
} else {
|
||
|
|
w.style.display = "block";
|
||
|
|
setTimeout(function(){
|
||
|
|
document.getElementById("searchbox").focus()
|
||
|
|
}, 30);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
||
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
||
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
||
|
|
/* Search is accomplished using CGI and will not work without it. */
|
||
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
||
|
|
document.getElementById("search_menubutton").style.display = "none";
|
||
|
|
}
|
||
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
||
|
|
function hideorshow(btn,obj){
|
||
|
|
var x = document.getElementById(obj);
|
||
|
|
var b = document.getElementById(btn);
|
||
|
|
if( x.style.display!='none' ){
|
||
|
|
x.style.display = 'none';
|
||
|
|
b.innerHTML='show';
|
||
|
|
}else{
|
||
|
|
x.style.display = '';
|
||
|
|
b.innerHTML='hide';
|
||
|
|
}
|
||
|
|
return false;
|
||
|
|
}
|
||
|
|
</script>
|
||
|
|
</div>
|
||
|
|
<!-- keywords: sqlite3_mutex_alloc sqlite3_mutex_enter sqlite3_mutex_free sqlite3_mutex_leave sqlite3_mutex_try -->
|
||
|
|
<div class=nosearch>
|
||
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
||
|
|
<h2>Mutexes</h2>
|
||
|
|
</div>
|
||
|
|
<blockquote><pre>
|
||
|
|
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*);
|
||
|
|
</pre></blockquote>
|
||
|
|
<p>
|
||
|
|
The SQLite core uses these routines for thread
|
||
|
|
synchronization. Though they are intended for internal
|
||
|
|
use by SQLite, code that links against SQLite is
|
||
|
|
permitted to use any of these routines.</p>
|
||
|
|
|
||
|
|
<p>The SQLite source code contains multiple implementations
|
||
|
|
of these mutex routines. An appropriate implementation
|
||
|
|
is selected automatically at compile-time. The following
|
||
|
|
implementations are available in the SQLite core:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> SQLITE_MUTEX_PTHREADS
|
||
|
|
<li> SQLITE_MUTEX_W32
|
||
|
|
<li> SQLITE_MUTEX_NOOP
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>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. The SQLITE_MUTEX_PTHREADS and
|
||
|
|
SQLITE_MUTEX_W32 implementations are appropriate for use on Unix
|
||
|
|
and Windows.</p>
|
||
|
|
|
||
|
|
<p>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. In this case the
|
||
|
|
application must supply a custom mutex implementation using the
|
||
|
|
<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigmutex">SQLITE_CONFIG_MUTEX</a> option of the sqlite3_config() function
|
||
|
|
before calling sqlite3_initialize() or any other public sqlite3_
|
||
|
|
function that calls sqlite3_initialize().</p>
|
||
|
|
|
||
|
|
<p>The sqlite3_mutex_alloc() routine allocates a new
|
||
|
|
mutex and returns a pointer to it. The sqlite3_mutex_alloc()
|
||
|
|
routine returns NULL if it is unable to allocate the requested
|
||
|
|
mutex. The argument to sqlite3_mutex_alloc() must one of these
|
||
|
|
integer constants:</p>
|
||
|
|
|
||
|
|
<p><ul>
|
||
|
|
<li> SQLITE_MUTEX_FAST
|
||
|
|
<li> SQLITE_MUTEX_RECURSIVE
|
||
|
|
<li> SQLITE_MUTEX_STATIC_MAIN
|
||
|
|
<li> SQLITE_MUTEX_STATIC_MEM
|
||
|
|
<li> SQLITE_MUTEX_STATIC_OPEN
|
||
|
|
<li> SQLITE_MUTEX_STATIC_PRNG
|
||
|
|
<li> SQLITE_MUTEX_STATIC_LRU
|
||
|
|
<li> SQLITE_MUTEX_STATIC_PMEM
|
||
|
|
<li> SQLITE_MUTEX_STATIC_APP1
|
||
|
|
<li> SQLITE_MUTEX_STATIC_APP2
|
||
|
|
<li> SQLITE_MUTEX_STATIC_APP3
|
||
|
|
<li> SQLITE_MUTEX_STATIC_VFS1
|
||
|
|
<li> SQLITE_MUTEX_STATIC_VFS2
|
||
|
|
<li> SQLITE_MUTEX_STATIC_VFS3
|
||
|
|
</ul></p>
|
||
|
|
|
||
|
|
<p>The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE)
|
||
|
|
cause sqlite3_mutex_alloc() to create
|
||
|
|
a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
|
||
|
|
is used but not necessarily so when SQLITE_MUTEX_FAST is used.
|
||
|
|
The mutex implementation does not need to make a distinction
|
||
|
|
between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
|
||
|
|
not want to. SQLite will only request a recursive mutex in
|
||
|
|
cases where it really needs one. If a faster non-recursive mutex
|
||
|
|
implementation is available on the host platform, the mutex subsystem
|
||
|
|
might return such a mutex in response to SQLITE_MUTEX_FAST.</p>
|
||
|
|
|
||
|
|
<p>The other allowed parameters to sqlite3_mutex_alloc() (anything other
|
||
|
|
than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return
|
||
|
|
a pointer to a static preexisting mutex. Nine 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
|
||
|
|
use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
|
||
|
|
SQLITE_MUTEX_RECURSIVE.</p>
|
||
|
|
|
||
|
|
<p>Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
|
||
|
|
or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
|
||
|
|
returns a different mutex on every call. For the static
|
||
|
|
mutex types, the same mutex is returned on every call that has
|
||
|
|
the same type number.</p>
|
||
|
|
|
||
|
|
<p>The sqlite3_mutex_free() routine deallocates a previously
|
||
|
|
allocated dynamic mutex. Attempting to deallocate a static
|
||
|
|
mutex results in undefined behavior.</p>
|
||
|
|
|
||
|
|
<p>The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
|
||
|
|
to enter a mutex. If another thread is already within the mutex,
|
||
|
|
sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
|
||
|
|
SQLITE_BUSY. The sqlite3_mutex_try() interface returns <a href="../rescode.html#ok">SQLITE_OK</a>
|
||
|
|
upon successful entry. Mutexes created using
|
||
|
|
SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
|
||
|
|
In such cases, the
|
||
|
|
mutex must be exited an equal number of times before another thread
|
||
|
|
can enter. If the same thread tries to enter any mutex other
|
||
|
|
than an SQLITE_MUTEX_RECURSIVE more than once, the behavior is undefined.</p>
|
||
|
|
|
||
|
|
<p>Some systems (for example, Windows 95) do not support the operation
|
||
|
|
implemented by sqlite3_mutex_try(). On those systems, sqlite3_mutex_try()
|
||
|
|
will always return SQLITE_BUSY. The SQLite core only ever uses
|
||
|
|
sqlite3_mutex_try() as an optimization so this is acceptable
|
||
|
|
behavior.</p>
|
||
|
|
|
||
|
|
<p>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 by the
|
||
|
|
calling thread or is not currently allocated.</p>
|
||
|
|
|
||
|
|
<p>If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or
|
||
|
|
sqlite3_mutex_leave() is a NULL pointer, then all three routines
|
||
|
|
behave as no-ops.</p>
|
||
|
|
|
||
|
|
<p>See also: <a href="../c3ref/mutex_held.html">sqlite3_mutex_held()</a> and <a href="../c3ref/mutex_held.html">sqlite3_mutex_notheld()</a>.
|
||
|
|
</p><p>See also lists of
|
||
|
|
<a href="objlist.html">Objects</a>,
|
||
|
|
<a href="constlist.html">Constants</a>, and
|
||
|
|
<a href="funclist.html">Functions</a>.</p>
|