← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/cam/intro.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/ref/cam/intro.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB Reference Guide: Berkeley DB Concurrent Data Store applications</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Concurrent Data Store Applications</dl></h3></td>
15
 
<td align=right><a href="../../ref/env/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/intro.html"><img src="../../images/next.gif" alt="Next"></a>
16
 
</td></tr></table>
17
 
<p>
18
 
<h1 align=center>Berkeley DB Concurrent Data Store applications</h1>
19
 
<p>It is often desirable to have concurrent read-write access to a database
20
 
when there is no need for full recoverability or transaction semantics.
21
 
For this class of applications, Berkeley DB provides an interface supporting
22
 
deadlock-free, multiple-reader/single writer access to the database.
23
 
This means that at any instant in time, there may be either multiple
24
 
readers accessing data or a single writer modifying data.  The
25
 
application is entirely unaware of which is happening, and Berkeley DB
26
 
implements the necessary locking and blocking to ensure this behavior.
27
 
<p>To create Berkeley DB Concurrent Data Store applications, you must first initialize an environment
28
 
by calling <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a>.  You must specify the <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a>
29
 
and <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flags to that interface.  It is an error to
30
 
specify any of the other <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> subsystem or recovery
31
 
configuration flags, for example, <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>,
32
 
<a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>, or <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a>.  All databases must, of
33
 
course, be created in this environment by using the <a href="../../api_c/db_create.html">db_create</a>
34
 
interface or <a href="../../api_cxx/db_class.html">Db</a> constructor, and specifying the environment
35
 
as an argument.
36
 
<p>Berkeley DB performs appropriate locking in its interface so that safe
37
 
enforcement of the deadlock-free, multiple-reader/single-writer semantic
38
 
is transparent to the application.  However, a basic understanding of
39
 
Berkeley DB Concurrent Data Store locking behavior is helpful when writing Berkeley DB Concurrent Data Store applications.
40
 
<p>Berkeley DB Concurrent Data Store
41
 
avoids deadlocks without the need for a deadlock detector by performing
42
 
all locking on an entire database at once (or on an entire environment
43
 
in the case of the <a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a> flag), and by ensuring that at
44
 
any given time only one thread of control is allowed to simultaneously
45
 
hold a read (shared) lock and attempt to acquire a write (exclusive)
46
 
lock.
47
 
<p>All open Berkeley DB cursors hold a read lock, which serves as a guarantee
48
 
that the database will not change beneath them;  likewise, all
49
 
non-cursor <a href="../../api_c/db_get.html">DB-&gt;get</a> operations temporarily acquire and release
50
 
a read lock that is held during the actual traversal of the database.
51
 
Because read locks will not conflict with each other, any number of
52
 
cursors in any number of threads of control may be open simultaneously,
53
 
and any number of <a href="../../api_c/db_get.html">DB-&gt;get</a> operations may be concurrently in
54
 
progress.
55
 
<p>To enforce the rule that only one thread of control at a time can
56
 
attempt to upgrade a read lock to a write lock, however, Berkeley DB must
57
 
forbid multiple cursors from attempting to write concurrently.  This is
58
 
done using the <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> flag to the <a href="../../api_c/db_cursor.html">DB-&gt;cursor</a>
59
 
interface.  This is the only difference between access method calls in
60
 
Berkeley DB Concurrent Data Store and in the other Berkeley DB products.  The <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> flag
61
 
causes the newly created cursor to be a "write" cursor; that is, a
62
 
cursor capable of performing writes as well as reads.  Only cursors thus
63
 
created are permitted to perform write operations (either deletes or
64
 
puts), and only one such cursor can exist at any given time.
65
 
<p>Any attempt to create a second write cursor or to perform a non-cursor
66
 
write operation while a write cursor is open will block until that write
67
 
cursor is closed.  Read cursors may open and perform reads without blocking
68
 
while a write cursor is extant.  However, any attempts to actually perform
69
 
a write, either using the write cursor or directly using the
70
 
<a href="../../api_c/db_put.html">DB-&gt;put</a> or <a href="../../api_c/db_del.html">DB-&gt;del</a> methods, will block until all read cursors
71
 
are closed.  This is how the multiple-reader/single-writer semantic is
72
 
enforced, and prevents reads from seeing an inconsistent database state
73
 
that may be an intermediate stage of a write operation.
74
 
<p>With these behaviors, Berkeley DB can guarantee deadlock-free concurrent
75
 
database access, so that multiple threads of control are free to perform
76
 
reads and writes without needing to handle synchronization themselves
77
 
or having to run a deadlock detector.  Because Berkeley DB has no knowledge
78
 
of which cursors belong to which threads, however, some care must be
79
 
taken to ensure that applications do not inadvertently block themselves,
80
 
causing the application to hang and be unable to proceed.  Some common
81
 
mistakes include the following:
82
 
<p><ol>
83
 
<p><li>Keeping a cursor open while issuing a <a href="../../api_c/db_put.html">DB-&gt;put</a> or <a href="../../api_c/db_del.html">DB-&gt;del</a>
84
 
access method call.
85
 
<p><li>Attempting to open a write cursor while a write cursor is already being
86
 
held open by the same thread of control.  Note that it is correct
87
 
operation for one thread of control to attempt to open a write cursor
88
 
or to perform a non-cursor write (<a href="../../api_c/db_put.html">DB-&gt;put</a> or <a href="../../api_c/db_del.html">DB-&gt;del</a>)
89
 
while a write cursor is already active in another thread.  It is only
90
 
a problem if these things are done within a single thread of control --
91
 
in which case that thread will block and never be able to release the
92
 
lock that is blocking it.
93
 
<p><li>Keeping a write cursor open for an extended period of time.
94
 
<p><li>Not testing Berkeley DB error return codes (if any cursor operation returns
95
 
an unexpected error, that cursor must still be closed).
96
 
<p><li>By default, Berkeley DB Concurrent Data Store does locking on a per-database basis.  For this reason,
97
 
accessing multiple databases in different orders in different threads
98
 
or processes, or leaving cursors open on one database while accessing
99
 
another database, can cause an application to hang.  If this behavior
100
 
is a requirement for the application, Berkeley DB should be configured to do
101
 
locking on an environment-wide basis.  See the <a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a> flag
102
 
of the <a href="../../api_c/env_set_flags.html">DB_ENV-&gt;set_flags</a> function for more information.
103
 
</ol>
104
 
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/intro.html"><img src="../../images/next.gif" alt="Next"></a>
105
 
</td></tr></table>
106
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
107
 
</body>
108
 
</html>