← 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/api_cxx/lock_vec.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/api_cxx/lock_vec.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: DbEnv::lock_vec</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>
15
 
<h1>DbEnv::lock_vec</h1>
16
 
</td>
17
 
<td align=right>
18
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
19
 
</td></tr></table>
20
 
<hr size=1 noshade>
21
 
<tt>
22
 
<h3><pre>
23
 
#include &lt;db_cxx.h&gt;
24
 
<p>
25
 
int
26
 
DbEnv::lock_vec(u_int32_t locker, u_int32_t flags,
27
 
    DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);
28
 
</pre></h3>
29
 
<h1>Description</h1>
30
 
<p>The DbEnv::lock_vec method atomically obtains and releases one or more locks
31
 
from the lock table.  The DbEnv::lock_vec method is intended to support
32
 
acquisition or trading of multiple locks under one lock table semaphore,
33
 
as is needed for lock coupling or in multigranularity locking for lock
34
 
escalation.
35
 
<p>The <b>locker</b> argument specified to DbEnv::lock_vec is an unsigned
36
 
32-bit integer quantity.  It represents the entity requesting or releasing
37
 
the locks.
38
 
<p>The <b>flags</b> value must be set to 0 or
39
 
the following value:
40
 
<p><dl compact>
41
 
<p><dt><a name="DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a><dd>If a lock cannot be granted because the requested lock conflicts with
42
 
an existing lock,
43
 
return DB_LOCK_NOTGRANTED or throw a
44
 
<a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> immediately instead of waiting for
45
 
the lock to become available.  In this case, if non-NULL,
46
 
<b>elistp</b> identifies the request that was not granted, or, if an
47
 
exception is thrown, the index of the request that was not granted can
48
 
be found by calling DbLockNotGrantedException.get_index.
49
 
</dl>
50
 
<p>The <b>list</b> array provided to DbEnv::lock_vec is typedef'd as
51
 
DB_LOCKREQ.  A DB_LOCKREQ structure has at least the following fields.
52
 
In order to ensure compatibility with future releases of Berkeley DB, all
53
 
fields of the DB_LOCKREQ structure that are not explicitly set should
54
 
be initialized to 0 before the first time the structure is used.  Do
55
 
this by declaring the structure external or static, or by calling
56
 
<b>memset</b>(3).
57
 
<p><dl compact>
58
 
<p><dt>lockop_t <a name="op">op</a>;<dd>The operation to be performed, which must be set to one of the
59
 
following values:
60
 
<p><dl compact>
61
 
<p><dt><a name="DB_LOCK_GET">DB_LOCK_GET</a><dd>Get the lock defined by the values of the <b>mode</b> and <b>obj</b>
62
 
structure fields, for the specified <b>locker</b>.  Upon return from
63
 
DbEnv::lock_vec, if the <b>lock</b> field is non-NULL, a reference
64
 
to the acquired lock is stored there.  (This reference is invalidated
65
 
by any call to DbEnv::lock_vec or <a href="../api_cxx/lock_put.html">DbEnv::lock_put</a> that releases the
66
 
lock.)
67
 
<p><dt><a name="DB_LOCK_GET_TIMEOUT">DB_LOCK_GET_TIMEOUT</a><dd>Identical to DB_LOCK_GET except that the value in the <b>timeout</b>
68
 
structure field overrides any previously specified timeout value for
69
 
this lock.  A value of 0 turns off any previously specified timeout.
70
 
<p><dt><a name="DB_LOCK_PUT">DB_LOCK_PUT</a><dd>The lock to which the <b>lock</b> structure field refers is released.
71
 
The <b>locker</b> argument, and <b>mode</b> and <b>obj</b> fields
72
 
are ignored.
73
 
<p><dt><a name="DB_LOCK_PUT_ALL">DB_LOCK_PUT_ALL</a><dd>All locks held by the specified <b>locker</b> are released.  The
74
 
<b>lock</b>, <b>mode</b>, and <b>obj</b> structure fields are
75
 
ignored.  Locks acquired in operations performed by the current call to
76
 
DbEnv::lock_vec which appear before the DB_LOCK_PUT_ALL
77
 
operation are released; those acquired in operations appearing after
78
 
the DB_LOCK_PUT_ALL operation are not released.
79
 
<p><dt><a name="DB_LOCK_PUT_OBJ">DB_LOCK_PUT_OBJ</a><dd>All locks held on the object <b>obj</b> are released.  The
80
 
<b>locker</b> argument and the <b>lock</b> and <b>mode</b> structure
81
 
fields are ignored.  Locks acquired in operations performed by the
82
 
current call to DbEnv::lock_vec that appear before the
83
 
DB_LOCK_PUT_OBJ operation are released; those acquired in
84
 
operations appearing after the DB_LOCK_PUT_OBJ operation are
85
 
not released.
86
 
<p><dt><a name="DB_LOCK_TIMEOUT">DB_LOCK_TIMEOUT</a><dd>Cause the specified <b>locker</b> to timeout immediately.  If the
87
 
database environment has not configured automatic deadlock detection,
88
 
the transaction will timeout the next time deadlock detection is
89
 
performed.  As transactions acquire locks on behalf of a single locker
90
 
ID, timing out the locker ID associated with a transaction will time
91
 
out the transaction itself.
92
 
</dl>
93
 
<p><dt>DB_LOCK <a name="lock">lock</a>;<dd>A lock reference.
94
 
<p><dt>const lockmode_t <a name="mode">mode</a>;<dd>The lock mode, used as an index into the environment's lock conflict matrix.
95
 
When using the default lock conflict matrix, <b>mode</b> must be set to one
96
 
of the following values:
97
 
<p><dl compact>
98
 
<dt><a name="DB_LOCK_READ">DB_LOCK_READ</a><dd>read (shared)
99
 
<dt><a name="DB_LOCK_WRITE">DB_LOCK_WRITE</a><dd>write (exclusive)
100
 
<dt><a name="DB_LOCK_IWRITE">DB_LOCK_IWRITE</a><dd>intention to write (shared)
101
 
<dt><a name="DB_LOCK_IREAD">DB_LOCK_IREAD</a><dd>intention to read (shared)
102
 
<dt><a name="DB_LOCK_IWR">DB_LOCK_IWR</a><dd>intention to read and write (shared)
103
 
</dl>
104
 
<p>See <a href="../api_cxx/env_set_lk_conflicts.html">DbEnv::set_lk_conflicts</a> and <a href="../ref/lock/stdmode.html">Standard Lock Modes</a> for more information on the lock conflict matrix.
105
 
<p><dt>const Dbt <a name="obj">obj</a>;<dd>An untyped byte string that specifies the object to be locked or
106
 
released.  Applications using the locking subsystem directly while also
107
 
doing locking via the Berkeley DB access methods must take care not to
108
 
inadvertently lock objects that happen to be equal to the unique file
109
 
IDs used to lock files.  See <a href="../ref/lock/am_conv.html">Access
110
 
method locking conventions</a> for more information.
111
 
<p><dt>u_int32_t timeout;<dd>The lock timeout value.
112
 
</dl>
113
 
<p>The <b>nlist</b> argument specifies the number of elements in the
114
 
<b>list</b> array.
115
 
<p>If any of the requested locks cannot be acquired, or any of the locks to
116
 
be released cannot be released, the operations before the failing
117
 
operation are guaranteed to have completed successfully, and
118
 
DbEnv::lock_vec returns a non-zero value.  In addition, if <b>elistp</b>
119
 
is not NULL, it is set to point to the DB_LOCKREQ entry that was being
120
 
processed when the error occurred.
121
 
<p>
122
 
Otherwise, the DbEnv::lock_vec method either returns a non-zero error value or throws an exception that
123
 
encapsulates a non-zero error value on failure, and returns 0 on success.
124
 
<h1>Errors</h1>
125
 
<p>The DbEnv::lock_vec method may fail and throw an exception or return a non-zero error for the following conditions:
126
 
<p><dl compact>
127
 
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
128
 
</dl>
129
 
<p><dl compact>
130
 
<p><dt>ENOMEM<dd>The maximum number of locks has been reached.
131
 
</dl>
132
 
<p>If the operation was selected to resolve a deadlock, the
133
 
DbEnv::lock_vec method will fail and
134
 
and either return <a href="../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or
135
 
throw a <a href="../api_cxx/deadlock_class.html">DbDeadlockException</a> exception.
136
 
<p>The DbEnv::lock_vec method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
137
 
If a catastrophic error has occurred, the DbEnv::lock_vec method may fail and
138
 
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
139
 
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
140
 
in which case all subsequent Berkeley DB calls will fail in the same way.
141
 
<h1>Class</h1>
142
 
<a href="../api_cxx/env_class.html">DbEnv</a>, <a href="../api_cxx/lock_class.html">DbLock</a>
143
 
<h1>See Also</h1>
144
 
<a href="../api_cxx/lock_list.html">Locking Subsystem and Related Methods</a>
145
 
</tt>
146
 
<table width="100%"><tr><td><br></td><td align=right>
147
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
148
 
</td></tr></table>
149
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
150
 
</body>
151
 
</html>