Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Documentation and comment updates in sqlite.h.in and mutex.c. (CVS 4299) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
7289079d6b4a7a160063e34c0f5e4363 |
User & Date: | drh 2007-08-25 16:21:30.000 |
Context
2007-08-25
| ||
16:31 | Create a fresh pthread_mutexattr_t every time a recursive mutex is allocated. Ticket #2588. (CVS 4300) (check-in: 3d746343ad user: drh tags: trunk) | |
16:21 | Documentation and comment updates in sqlite.h.in and mutex.c. (CVS 4299) (check-in: 7289079d6b user: drh tags: trunk) | |
14:49 | Clarification in the documentation of the sqlite3_mutex_held() and sqlite3_mutex_notheld() interfaces. Make it clear that these routines are only for use inside assert(). (CVS 4298) (check-in: a6bbf6eaf6 user: drh tags: trunk) | |
Changes
Changes to src/mutex.c.
︙ | ︙ | |||
8 9 10 11 12 13 14 | ** May you find forgiveness for yourself and forgive others. ** May you share freely, never taking more than you give. ** ************************************************************************* ** This file contains the C functions that implement mutexes for ** use by the SQLite core. ** | | | > | > > > > > > > > > > > > > | 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 | ** May you find forgiveness for yourself and forgive others. ** May you share freely, never taking more than you give. ** ************************************************************************* ** This file contains the C functions that implement mutexes for ** use by the SQLite core. ** ** $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 ** omitted and equivalent functionality must be provided by the ** application that links against the SQLite library. */ #ifndef SQLITE_MUTEX_APPDEF /* This is the beginning of internal implementation of mutexes ** for SQLite. */ #include "sqliteInt.h" /* ** 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 # undef SQLITE_MUTEX_NOOP # define SQLITE_MUTEX_NOOP_DEBUG #endif #if defined(SQLITE_MUTEX_NOOP) && SQLITE_THREADSAFE && OS_UNIX |
︙ | ︙ | |||
110 111 112 113 114 115 116 | ** for test purposes. */ /* ** The mutex object */ struct sqlite3_mutex { | | | | 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | ** for test purposes. */ /* ** The mutex object */ struct sqlite3_mutex { int id; /* The mutex type */ int cnt; /* Number of entries without a matching leave */ }; /* ** The sqlite3_mutex_alloc() routine allocates a new ** mutex and returns a pointer to it. If it returns NULL ** that means that a mutex could not be allocated. */ |
︙ | ︙ | |||
166 167 168 169 170 171 172 | ** 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 other kind of mutex ** more than once, the behavior is undefined. */ void sqlite3_mutex_enter(sqlite3_mutex *p){ assert( p ); | | | < < | > > | 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | ** 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 other kind of mutex ** more than once, the behavior is undefined. */ void sqlite3_mutex_enter(sqlite3_mutex *p){ assert( p ); assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); p->cnt++; } int sqlite3_mutex_try(sqlite3_mutex *p){ assert( p ); assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); p->cnt++; return SQLITE_OK; } /* ** 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. */ void sqlite3_mutex_leave(sqlite3_mutex *p){ assert( p ); assert( sqlite3_mutex_held(p) ); p->cnt--; assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) ); } /* ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are ** intended for use inside assert() statements. */ int sqlite3_mutex_held(sqlite3_mutex *p){ |
︙ | ︙ | |||
365 366 367 368 369 370 371 372 373 374 375 376 | ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ void sqlite3_mutex_leave(sqlite3_mutex *p){ assert( p ); assert( sqlite3_mutex_held(p) ); p->nRef--; pthread_mutex_unlock(&p->mutex); } /* ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are | > | > > > > > > > > > > > > > > | 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 | ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ void sqlite3_mutex_leave(sqlite3_mutex *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 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 /********************** Windows Mutex Implementation ********************** ** ** This implementation of mutexes is built using the win32 API. */ |
︙ | ︙ | |||
529 530 531 532 533 534 535 536 537 538 539 540 | ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ void sqlite3_mutex_leave(sqlite3_mutex *p){ assert( p->nRef>0 ); assert( p->owner==GetCurrentThreadId() ); p->nRef--; LeaveCriticalSection(&p->mutex); } /* ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are | > | | 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 | ** is undefined if the mutex is not currently entered or ** is not currently allocated. SQLite will never do either. */ void sqlite3_mutex_leave(sqlite3_mutex *p){ 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 only inside assert() statements. */ int sqlite3_mutex_held(sqlite3_mutex *p){ return p==0 || (p->nRef!=0 && p->owner==GetCurrentThreadId()); } int sqlite3_mutex_notheld(sqlite3_mutex *p){ return p==0 || p->nRef==0 || p->owner!=GetCurrentThreadId(); } #endif /* SQLITE_MUTEX_WIN */ #endif /* !defined(SQLITE_MUTEX_APPDEF) */ |
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.242 2007/08/25 16:21:30 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
113 114 115 116 117 118 119 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Database Connection Handle ** ** 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 | | | | | | | 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | int sqlite3_libversion_number(void); /* ** CAPI3REF: Database Connection Handle ** ** 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 ** object. */ typedef struct sqlite3 sqlite3; /* ** CAPI3REF: 64-Bit Integer Types |
︙ | ︙ | |||
900 901 902 903 904 905 906 | ** Instead of invoking a user-supplied callback for each row of the ** result, this routine remembers each row of the result in memory ** obtained from [sqlite3_malloc()], then returns all of the result after the ** query has finished. ** ** As an example, suppose the query result where this table: ** | | | | | | | | | | | | | | 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 | ** Instead of invoking a user-supplied callback for each row of the ** result, this routine remembers each row of the result in memory ** obtained from [sqlite3_malloc()], then returns all of the result after the ** query has finished. ** ** As an example, suppose the query result where this table: ** ** <blockquote><pre> ** Name | Age ** ----------------------- ** Alice | 43 ** Bob | 28 ** Cindy | 21 ** </pre></blockquote> ** ** If the 3rd argument were &azResult then after the function returns ** azResult will contain the following data: ** ** <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 ** set to 2. In general, the number of values inserted into azResult ** will be ((*nrow) + 1)*(*ncolumn). ** ** After the calling function has finished using the result, it should |
︙ | ︙ | |||
1047 1048 1049 1050 1051 1052 1053 | char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem ** ** The SQLite core uses these three routines for all of its own | | | > > > > > > > > > > > | 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 | char *sqlite3_vmprintf(const char*, va_list); char *sqlite3_snprintf(int,char*,const char*, ...); /* ** CAPI3REF: Memory Allocation Subsystem ** ** The SQLite core uses these three routines for all of its own ** 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 ** ** <blockquote> SQLITE_OMIT_MEMORY_ALLOCATION </blockquote> ** ** then no implementation is provided for these routines by ** SQLite. The application that links against SQLite is ** 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); void sqlite3_free(void*); /* ** CAPI3REF: Memory Allocator Statistics |
︙ | ︙ | |||
1109 1110 1111 1112 1113 1114 1115 | ** the recursive calls. ** ** The [sqlite3_soft_heap_limit()] interface works by registering ** a memory alarm at the soft heap limit and invoking ** [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 | | > > > | 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 | ** the recursive calls. ** ** The [sqlite3_soft_heap_limit()] interface works by registering ** a memory alarm at the soft heap limit and invoking ** [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. 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), void *pArg, sqlite3_int64 iThreshold ); |
︙ | ︙ | |||
1629 1630 1631 1632 1633 1634 1635 | ** if the same host parameter name is used multiple times, each occurrance ** is given the same number, so the value returned in that case is the number ** of unique host parameter names. If host parameters of the form "?NNN" ** are used (where NNN is an integer) then there might be gaps in the ** numbering and the value returned by this interface is the index of the ** host parameter with the largest index value. ** | | | 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 | ** if the same host parameter name is used multiple times, each occurrance ** is given the same number, so the value returned in that case is the number ** of unique host parameter names. If host parameters of the form "?NNN" ** are used (where NNN is an integer) then there might be gaps in the ** 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 be [sqlite3_finalize | finalized] ** prior to this routine returnning. Otherwise the results are undefined ** and probably undesirable. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter |
︙ | ︙ | |||
1959 1960 1961 1962 1963 1964 1965 | ** example, if the internal representation is FLOAT and a text result ** is requested, [sqlite3_snprintf()] is used internally to do the conversion ** automatically. The following table details the conversions that ** are applied: ** ** <blockquote> ** <table border="1"> | | < | 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 | ** example, if the internal representation is FLOAT and a text result ** is requested, [sqlite3_snprintf()] is used internally to do the conversion ** automatically. The following table details the conversions that ** are applied: ** ** <blockquote> ** <table border="1"> ** <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 ** <tr><td> NULL <td> TEXT <td> Result is NULL pointer ** <tr><td> NULL <td> BLOB <td> Result is NULL pointer ** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float ** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer |
︙ | ︙ | |||
2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 | ** This function causes the current thread to suspend execution ** a number of milliseconds specified in its parameter. ** ** If the operating system does not support sleep requests with ** 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. */ int sqlite3_sleep(int); /* ** CAPI3REF: Name Of The Folder Holding Temporary Files ** ** If this global variable is made to point to a string which is | > > > | 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 | ** This function causes the current thread to suspend execution ** a number of milliseconds specified in its parameter. ** ** If the operating system does not support sleep requests with ** 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); /* ** CAPI3REF: Name Of The Folder Holding Temporary Files ** ** If this global variable is made to point to a string which is |
︙ | ︙ | |||
2692 2693 2694 2695 2696 2697 2698 | ** implementation. This means that if the application also uses the ** memory alarm interface it will interfere with the operation of the ** soft heap limit and undefined behavior will result. ** ** 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 | > > > | | 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 | ** implementation. This means that if the application also uses the ** memory alarm interface it will interfere with the operation of the ** soft heap limit and undefined behavior will result. ** ** 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 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); /* ** CAPI3REF: Extract Metadata About A Column Of A Table ** ** This routine |
︙ | ︙ | |||
3222 3223 3224 3225 3226 3227 3228 | ** ** 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. ** ** The SQLite source code contains multiple implementations | | | > | < < < < | > > > | | | > > | 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 | ** ** 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. ** ** 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: ** ** <ul> ** <li> SQLITE_MUTEX_PTHREAD ** <li> SQLITE_MUTEX_WIN ** <li> SQLITE_MUTEX_NOOP ** </ul> ** ** 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_PTHREAD ** and SQLITE_MUTEX_WIN implementations are appropriate for ** use on unix and windows. ** ** 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 here become external ** references in the SQLite library for which implementations ** 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 ** that means that a mutex could not be allocated. SQLite ** will unwind its stack and return an error. The argument ** to sqlite3_mutex_alloc() is one of these integer constants: ** |
︙ | ︙ | |||
3271 3272 3273 3274 3275 3276 3277 | ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does ** not want to. But 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. ** ** The other allowed parameters to sqlite3_mutex_alloc() each return | | | 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 | ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does ** not want to. But 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. ** ** The other allowed parameters to sqlite3_mutex_alloc() each return ** 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 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or ** SQLITE_MUTEX_RECURSIVE. ** ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST |
︙ | ︙ | |||
3302 3303 3304 3305 3306 3307 3308 | ** 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 other kind of mutex ** more than once, the behavior is undefined. SQLite will never exhibit ** such behavior in its own use of mutexes. ** | | | | > > > > > > > > > > > > | > > > > > | | > | | | | | > < < < < < | 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 | ** 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 other kind of mutex ** more than once, the behavior is undefined. SQLite will never exhibit ** such behavior in its own use of mutexes. ** ** 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. 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. 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 ** clearly the mutex cannot be held if it does not exist. But the ** the reason the mutex does not exist is because the build is not ** using mutexes. And we do not want the assert() containing the ** call to sqlite3_mutex_held() to fail, so a non-zero return is ** the appropriate thing to do. The sqlite3_mutex_notheld() ** interface should also return 1 when given a NULL pointer. */ int sqlite3_mutex_held(sqlite3_mutex*); int sqlite3_mutex_notheld(sqlite3_mutex*); /* ** CAPI3REF: Mutex Types ** ** The [sqlite3_mutex_alloc()] interface takes a single argument |
︙ | ︙ |