<!--$Id: inc.html,v 1.2 2004/03/30 01:22:59 jtownsen Exp $--> <!--Copyright 1997-2003 by Sleepycat Software, Inc.--> <!--All rights reserved.--> <!--See the file LICENSE for redistribution information.--> <html> <head> <title>Berkeley DB Reference Guide: Isolation</title> <meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> <meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> </head> <body bgcolor=white> <table width="100%"><tr valign=top> <td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> <td align=right><a href="../transapp/atomicity.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../transapp/read.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p> <h3 align=center>Isolation</h3> <p>The third reason listed for using transactions was <i>isolation</i>. Consider an application suite in which multiple threads of control (multiple processes or threads in one or more processes) are changing the values associated with a key in one or more databases. Specifically, they are taking the current value, incrementing it, and then storing it back into the database.</p> <p>Such an application requires isolation. Because we want to change a value in the database, we must make sure that after we read it, no other thread of control modifies it. For example, assume that both thread #1 and thread #2 are doing similar operations in the database, where thread #1 is incrementing records by 3, and thread #2 is incrementing records by 5. We want to increment the record by a total of 8. If the operations interleave in the right (well, wrong) order, that is not what will happen:</p> <blockquote><pre>thread #1 <b>read</b> record: the value is 2 thread #2 <b>read</b> record: the value is 2 thread #2 <b>write</b> record + 5 back into the database (new value 7) thread #1 <b>write</b> record + 3 back into the database (new value 5)</pre></blockquote> <p>As you can see, instead of incrementing the record by a total of 8, we've incremented it only by 3 because thread #1 overwrote thread #2's change. By wrapping the operations in transactions, we ensure that this cannot happen. In a transaction, when the first thread reads the record, locks are acquired that will not be released until the transaction finishes, guaranteeing that all other readers and writers will block, waiting for the first thread's transaction to complete (or to be aborted).</p> <p>Here is an example function that does transaction-protected increments on database records to ensure isolation:</p> <blockquote><pre>int main(int argc, char *argv) { extern int optind; DB *db_cats, *db_color, *db_fruit; DB_ENV *dbenv; int ch; <p> while ((ch = getopt(argc, argv, "")) != EOF) switch (ch) { case '?': default: usage(); } argc -= optind; argv += optind; <p> env_dir_create(); env_open(&dbenv); <p> /* Open database: Key is fruit class; Data is specific type. */ db_open(dbenv, &db_fruit, "fruit", 0); <p> /* Open database: Key is a color; Data is an integer. */ db_open(dbenv, &db_color, "color", 0); <p> /* * Open database: * Key is a name; Data is: company name, cat breeds. */ db_open(dbenv, &db_cats, "cats", 1); <p> add_fruit(dbenv, db_fruit, "apple", "yellow delicious"); <p> <b> add_color(dbenv, db_color, "blue", 0); add_color(dbenv, db_color, "blue", 3);</b> <p> return (0); } <p> <b>int add_color(DB_ENV *dbenv, DB *dbp, char *color, int increment) { DBT key, data; DB_TXN *tid; int fail, original, ret, t_ret; char buf64; <p> /* Initialization. */ memset(&key, 0, sizeof(key)); key.data = color; key.size = strlen(color); memset(&data, 0, sizeof(data)); data.flags = DB_DBT_MALLOC; <p> for (fail = 0;;) { /* Begin the transaction. */ if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); exit (1); } <p> /* * Get the key. If it exists, we increment the value. If it * doesn't exist, we create it. */ switch (ret = dbp->get(dbp, tid, &key, &data, DB_RMW)) { case 0: original = atoi(data.data); break; case DB_LOCK_DEADLOCK: default: /* Retry the operation. */ if ((t_ret = tid->abort(tid)) != 0) { dbenv->err(dbenv, t_ret, "DB_TXN->abort"); exit (1); } if (fail++ == MAXIMUM_RETRY) return (ret); continue; case DB_NOTFOUND: original = 0; break; } if (data.data != NULL) free(data.data); <p> /* Create the new data item. */ (void)snprintf(buf, sizeof(buf), "%d", original + increment); data.data = buf; data.size = strlen(buf) + 1; <p> /* Store the new value. */ switch (ret = dbp->put(dbp, tid, &key, &data, 0)) { case 0: /* Success: commit the change. */ if ((ret = tid->commit(tid, 0)) != 0) { dbenv->err(dbenv, ret, "DB_TXN->commit"); exit (1); } return (0); case DB_LOCK_DEADLOCK: default: /* Retry the operation. */ if ((t_ret = tid->abort(tid)) != 0) { dbenv->err(dbenv, t_ret, "DB_TXN->abort"); exit (1); } if (fail++ == MAXIMUM_RETRY) return (ret); break; } } }</b></pre></blockquote> <p>The <a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a> flag in the <a href="../../api_c/db_get.html">DB->get</a> call specifies a write lock should be acquired on the key/data pair, instead of the more obvious read lock. We do this because the application expects to write the key/data pair in a subsequent operation, and the transaction is much more likely to deadlock if we first obtain a read lock and subsequently a write lock, than if we obtain the write lock initially.</p> <table width="100%"><tr><td><br></td><td align=right><a href="../transapp/atomicity.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../transapp/read.html"><img src="../../images/next.gif" alt="Next"></a> </td></tr></table> <p><font size=1><a href="../../sleepycat/legal.html">Copyright (c) 1996-2003</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font> </body> </html>