/*

** 2009 March 3

**

** The author disclaims copyright to this source code. In place of

** a legal notice, here is a blessing:

**

** May you do good and not evil.

** May you find forgiveness for yourself and forgive others.

** May you share freely, never taking more than you give.

**

*************************************************************************

**

** This file contains the implementation of the sqlite3_unlock_notify()

** API method and its associated functionality.

*/

#include "sqliteInt.h"

#include "btreeInt.h"

/* Omit this entire file if SQLITE_ENABLE_UNLOCK_NOTIFY is not defined. */

#ifdef SQLITE_ENABLE_UNLOCK_NOTIFY

/*

** Public interfaces:

**

** sqlite3ConnectionBlocked()

** sqlite3ConnectionUnlocked()

** sqlite3ConnectionClosed()

** sqlite3_unlock_notify()

*/

#define assertMutexHeld() \

assert( sqlite3_mutex_held(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER)) )

/*

** Head of a linked list of all sqlite3 objects created by this process

** for which either sqlite3.pBlockingConnection or sqlite3.pUnlockConnection

** is not NULL. This variable may only accessed while the STATIC_MASTER

** mutex is held.

*/

static sqlite3 *SQLITE_WSD sqlite3BlockedList = 0;

#ifndef NDEBUG

/*

** This function is a complex assert() that verifies the following

** properties of the blocked connections list:

**

** 1) Each entry in the list has a non-NULL value for either

** pUnlockConnection or pBlockingConnection, or both.

**

** 2) All entries in the list that share a common value for

** xUnlockNotify are grouped together.

**

** 3) If the argument db is not NULL, then none of the entries in the

** blocked connections list have pUnlockConnection or pBlockingConnection

** set to db. This is used when closing connection db.

*/

static void checkListProperties(sqlite3 *db){

sqlite3 *p;

for(p=sqlite3BlockedList; p; p=p->pNextBlocked){

int seen = 0;

sqlite3 *p2;

/* Verify property (1) */

assert( p->pUnlockConnection || p->pBlockingConnection );

/* Verify property (2) */

for(p2=sqlite3BlockedList; p2!=p; p2=p2->pNextBlocked){

if( p2->xUnlockNotify==p->xUnlockNotify ) seen = 1;

assert( p2->xUnlockNotify==p->xUnlockNotify || !seen );

assert( db==0 || p->pUnlockConnection!=db );

assert( db==0 || p->pBlockingConnection!=db );

}

}

}

#else

# define checkListProperties(x)

#endif

/*

** Remove connection db from the blocked connections list. If connection

** db is not currently a part of the list, this function is a no-op.

*/

static void removeFromBlockedList(sqlite3 *db){

sqlite3 **pp;

assertMutexHeld();

for(pp=&sqlite3BlockedList; *pp; pp = &(*pp)->pNextBlocked){

if( *pp==db ){

*pp = (*pp)->pNextBlocked;

break;

}

}

}

/*

** Add connection db to the blocked connections list. It is assumed

** that it is not already a part of the list.

*/

static void addToBlockedList(sqlite3 *db){

sqlite3 **pp;

assertMutexHeld();

for(

pp=&sqlite3BlockedList;

*pp && (*pp)->xUnlockNotify!=db->xUnlockNotify;

pp=&(*pp)->pNextBlocked

);

db->pNextBlocked = *pp;

*pp = db;

}

/*

** Obtain the STATIC_MASTER mutex.

*/

static void enterMutex(void){

sqlite3_mutex_enter(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));

checkListProperties(0);

}

/*

** Release the STATIC_MASTER mutex.

*/

static void leaveMutex(void){

assertMutexHeld();

checkListProperties(0);

sqlite3_mutex_leave(sqlite3MutexAlloc(SQLITE_MUTEX_STATIC_MASTER));

}

/*

** Register an unlock-notify callback.

**

** This is called after connection "db" has attempted some operation

** but has received an SQLITE_LOCKED error because another connection

** (call it pOther) in the same process was busy using the same shared

** cache. pOther is found by looking at db->pBlockingConnection.

**

** If there is no blocking connection, the callback is invoked immediately,

** before this routine returns.

**

** If pOther is already blocked on db, then report SQLITE_LOCKED, to indicate

** a deadlock.

**

** Otherwise, make arrangements to invoke xNotify when pOther drops

** its locks.

**

** Each call to this routine overrides any prior callbacks registered

** on the same "db". If xNotify==0 then any prior callbacks are immediately

** cancelled.

*/

int sqlite3_unlock_notify(

sqlite3 *db,

void (*xNotify)(void **, int),

void *pArg

){

int rc = SQLITE_OK;

sqlite3_mutex_enter(db->mutex);

enterMutex();

if( xNotify==0 ){

removeFromBlockedList(db);

db->pBlockingConnection = 0;

db->pUnlockConnection = 0;

db->xUnlockNotify = 0;

db->pUnlockArg = 0;

}else if( 0==db->pBlockingConnection ){

/* The blocking transaction has been concluded. Or there never was a

** blocking transaction. In either case, invoke the notify callback

** immediately.

*/

xNotify(&pArg, 1);

}else{

sqlite3 *p;

for(p=db->pBlockingConnection; p && p!=db; p=p->pUnlockConnection){}

if( p ){

rc = SQLITE_LOCKED; /* Deadlock detected. */

}else{

db->pUnlockConnection = db->pBlockingConnection;

db->xUnlockNotify = xNotify;

db->pUnlockArg = pArg;

removeFromBlockedList(db);

addToBlockedList(db);

}

}

leaveMutex();

assert( !db->mallocFailed );

sqlite3Error(db, rc, (rc?"database is deadlocked":0));

sqlite3_mutex_leave(db->mutex);

return rc;

}

/*

** This function is called while stepping or preparing a statement

** associated with connection db. The operation will return SQLITE_LOCKED

** to the user because it requires a lock that will not be available

** until connection pBlocker concludes its current transaction.

*/

void sqlite3ConnectionBlocked(sqlite3 *db, sqlite3 *pBlocker){

enterMutex();

if( db->pBlockingConnection==0 && db->pUnlockConnection==0 ){

addToBlockedList(db);

}

db->pBlockingConnection = pBlocker;

leaveMutex();

}

/*

** This function is called when

** the transaction opened by database db has just finished. Locks held

** by database connection db have been released.

**

** This function loops through each entry in the blocked connections

** list and does the following:

**

** 1) If the sqlite3.pBlockingConnection member of a list entry is

** set to db, then set pBlockingConnection=0.

**

** 2) If the sqlite3.pUnlockConnection member of a list entry is

** set to db, then invoke the configured unlock-notify callback and

** set pUnlockConnection=0.

**

** 3) If the two steps above mean that pBlockingConnection==0 and

** pUnlockConnection==0, remove the entry from the blocked connections

** list.

*/

void sqlite3ConnectionUnlocked(sqlite3 *db){

void (*xUnlockNotify)(void **, int) = 0; /* Unlock-notify cb to invoke */

int nArg = 0; /* Number of entries in aArg[] */

sqlite3 **pp; /* Iterator variable */

void **aArg; /* Arguments to the unlock callback */

void **aDyn = 0; /* Dynamically allocated space for aArg[] */

void *aStatic[16]; /* Starter space for aArg[]. No malloc required */

aArg = aStatic;

enterMutex(); /* Enter STATIC_MASTER mutex */

/* This loop runs once for each entry in the blocked-connections list. */

for(pp=&sqlite3BlockedList; *pp; /* no-op */ ){

sqlite3 *p = *pp;

/* Step 1. */

if( p->pBlockingConnection==db ){

p->pBlockingConnection = 0;

}

/* Step 2. */

if( p->pUnlockConnection==db ){

assert( p->xUnlockNotify );

if( p->xUnlockNotify!=xUnlockNotify && nArg!=0 ){

xUnlockNotify(aArg, nArg);

nArg = 0;

}

sqlite3BeginBenignMalloc();

assert( aArg==aDyn || (aDyn==0 && aArg==aStatic) );

assert( nArg<=(int)ArraySize(aStatic) || aArg==aDyn );

if( (!aDyn && nArg==(int)ArraySize(aStatic))

|| (aDyn && nArg==(int)(sqlite3MallocSize(aDyn)/sizeof(void*)))

){

/* The aArg[] array needs to grow. */

void **pNew = (void **)sqlite3Malloc(nArg*sizeof(void *)*2);

if( pNew ){

memcpy(pNew, aArg, nArg*sizeof(void *));

sqlite3_free(aDyn);

aDyn = aArg = pNew;

}else{

/* This occurs when the array of context pointers that need to

** be passed to the unlock-notify callback is larger than the

** aStatic[] array allocated on the stack and the attempt to

** allocate a larger array from the heap has failed.

**

** This is a difficult situation to handle. Returning an error

** code to the caller is insufficient, as even if an error code

** is returned the transaction on connection db will still be

** closed and the unlock-notify callbacks on blocked connections

** will go unissued. This might cause the application to wait

** indefinitely for an unlock-notify callback that will never

** arrive.

**

** Instead, invoke the unlock-notify callback with the context

** array already accumulated. We can then clear the array and

** begin accumulating any further context pointers without

** requiring any dynamic allocation. This is sub-optimal because

** it means that instead of one callback with a large array of

** context pointers the application will receive two or more

** callbacks with smaller arrays of context pointers, which will

** reduce the applications ability to prioritize multiple

** connections. But it is the best that can be done under the

** circumstances.

*/

xUnlockNotify(aArg, nArg);

nArg = 0;

}

}

sqlite3EndBenignMalloc();

aArg[nArg++] = p->pUnlockArg;

xUnlockNotify = p->xUnlockNotify;

p->pUnlockConnection = 0;

p->xUnlockNotify = 0;

p->pUnlockArg = 0;

}

/* Step 3. */

if( p->pBlockingConnection==0 && p->pUnlockConnection==0 ){

/* Remove connection p from the blocked connections list. */

*pp = p->pNextBlocked;

p->pNextBlocked = 0;

}else{

pp = &p->pNextBlocked;

}

}

if( nArg!=0 ){

xUnlockNotify(aArg, nArg);

}

sqlite3_free(aDyn);

leaveMutex(); /* Leave STATIC_MASTER mutex */

}

/*

** This is called when the database connection passed as an argument is

** being closed. The connection is removed from the blocked list.

*/

void sqlite3ConnectionClosed(sqlite3 *db){

sqlite3ConnectionUnlocked(db);

enterMutex();

removeFromBlockedList(db);

checkListProperties(db);

leaveMutex();

}

#endif