167 lines
9.4 KiB
HTML
167 lines
9.4 KiB
HTML
<!--$Id: lock_vec.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: DbEnv::lock_vec</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,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>
|
|
<b>DbEnv::lock_vec</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db_cxx.h>
|
|
<p>
|
|
int
|
|
DbEnv::lock_vec(u_int32_t locker, u_int32_t flags,
|
|
DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DbEnv::lock_vec</b>
|
|
<p>The DbEnv::lock_vec method atomically obtains and releases one or more locks
|
|
from the lock table. The DbEnv::lock_vec method is intended to support
|
|
acquisition or trading of multiple locks under one lock table semaphore,
|
|
as is needed for lock coupling or in multigranularity locking for lock
|
|
escalation.</p>
|
|
<p>If any of the requested locks cannot be acquired, or any of the locks to
|
|
be released cannot be released, the operations before the failing
|
|
operation are guaranteed to have completed successfully, and
|
|
DbEnv::lock_vec returns a non-zero value. In addition, if
|
|
<b>elistp</b> is not NULL, it is set to point to the DB_LOCKREQ entry
|
|
that was being processed when the error occurred.</p>
|
|
<p>Unless otherwise specified, the DbEnv::lock_vec method
|
|
either returns a non-zero error value
|
|
or throws an exception that encapsulates a non-zero error value on
|
|
failure, and returns 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>elistp</b><ul compact><li>If an error occurs, and the <b>elistp</b> parameter is non-NULL, it
|
|
is set to point to the DB_LOCKREQ entry that was being processed when
|
|
the error occurred.</ul>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or
|
|
the following value:
|
|
<br>
|
|
<b><a name="DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a></b><ul compact><li>If a lock cannot be granted because the requested lock conflicts with
|
|
an existing lock,
|
|
return DB_LOCK_NOTGRANTED or throw a
|
|
<a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> immediately instead of waiting for
|
|
the lock to become available. In this case, if non-NULL,
|
|
<b>elistp</b> identifies the request that was not granted, or, if an
|
|
exception is thrown, the index of the request that was not granted can
|
|
be found by calling DbLockNotGrantedException.get_index.</ul>
|
|
<br></ul>
|
|
<b>locker</b><ul compact><li>The <b>locker</b> parameter is an unsigned 32-bit integer quantity. It
|
|
represents the entity requesting or releasing the lock.</ul>
|
|
<b>list</b><ul compact><li>The <b>list</b> array provided to DbEnv::lock_vec is typedef'd as
|
|
DB_LOCKREQ.
|
|
<p>To ensure compatibility with future releases of Berkeley DB, all
|
|
fields of the DB_LOCKREQ structure that are not explicitly set should
|
|
be initialized to 0 before the first time the structure is used. Do
|
|
this by declaring the structure external or static, or by calling
|
|
<b>memset</b>(3).</p>
|
|
<p>A DB_LOCKREQ structure has at least the following fields:</p>
|
|
<br>
|
|
<b>lockop_t <a name="op">op</a>;</b><ul compact><li>The operation to be performed, which must be set to one of the
|
|
following values:</ul>
|
|
<br>
|
|
<b><a name="DB_LOCK_GET">DB_LOCK_GET</a></b><ul compact><li>Get the lock defined by the values of the <b>mode</b> and <b>obj</b>
|
|
structure fields, for the specified <b>locker</b>. Upon return from
|
|
DbEnv::lock_vec, if the <b>lock</b> field is non-NULL, a reference
|
|
to the acquired lock is stored there. (This reference is invalidated
|
|
by any call to DbEnv::lock_vec or <a href="../api_cxx/lock_put.html">DbEnv::lock_put</a> that releases the
|
|
lock.)</ul>
|
|
<b><a name="DB_LOCK_GET_TIMEOUT">DB_LOCK_GET_TIMEOUT</a></b><ul compact><li>Identical to DB_LOCK_GET except that the value in the <b>timeout</b>
|
|
structure field overrides any previously specified timeout value for
|
|
this lock. A value of 0 turns off any previously specified timeout.</ul>
|
|
<b><a name="DB_LOCK_PUT">DB_LOCK_PUT</a></b><ul compact><li>The lock to which the <b>lock</b> structure field refers is released.
|
|
The <b>locker</b> parameter, and <b>mode</b> and <b>obj</b> fields
|
|
are ignored.</ul>
|
|
<b><a name="DB_LOCK_PUT_ALL">DB_LOCK_PUT_ALL</a></b><ul compact><li>All locks held by the specified <b>locker</b> are released. The
|
|
<b>lock</b>, <b>mode</b>, and <b>obj</b> structure fields are
|
|
ignored. Locks acquired in operations performed by the current call to
|
|
DbEnv::lock_vec which appear before the DB_LOCK_PUT_ALL
|
|
operation are released; those acquired in operations appearing after
|
|
the DB_LOCK_PUT_ALL operation are not released.</ul>
|
|
<b><a name="DB_LOCK_PUT_OBJ">DB_LOCK_PUT_OBJ</a></b><ul compact><li>All locks held on <b>obj</b> are released. The <b>locker</b>
|
|
parameter and the <b>lock</b> and <b>mode</b> structure fields are
|
|
ignored. Locks acquired in operations performed by the current call to
|
|
DbEnv::lock_vec that appear before the DB_LOCK_PUT_OBJ
|
|
operation are released; those acquired in operations appearing after the
|
|
DB_LOCK_PUT_OBJ operation are not released.</ul>
|
|
<b><a name="DB_LOCK_TIMEOUT">DB_LOCK_TIMEOUT</a></b><ul compact><li>Cause the specified <b>locker</b> to timeout immediately. If the
|
|
database environment has not configured automatic deadlock detection,
|
|
the transaction will timeout the next time deadlock detection is
|
|
performed. As transactions acquire locks on behalf of a single locker
|
|
ID, timing out the locker ID associated with a transaction will time
|
|
out the transaction itself.</ul>
|
|
<br>
|
|
<b>DB_LOCK <a name="lock">lock</a>;</b><ul compact><li>A lock reference.</ul>
|
|
<b>const lockmode_t <a name="mode">mode</a>;</b><ul compact><li>The lock mode, used as an index into the environment's lock conflict matrix.
|
|
When using the default lock conflict matrix, <b>mode</b> must be set to one
|
|
of the following values:
|
|
<br>
|
|
<b><a name="DB_LOCK_READ">DB_LOCK_READ</a></b><ul compact><li>read (shared)</ul>
|
|
<b><a name="DB_LOCK_WRITE">DB_LOCK_WRITE</a></b><ul compact><li>write (exclusive)</ul>
|
|
<b><a name="DB_LOCK_IWRITE">DB_LOCK_IWRITE</a></b><ul compact><li>intention to write (shared)</ul>
|
|
<b><a name="DB_LOCK_IREAD">DB_LOCK_IREAD</a></b><ul compact><li>intention to read (shared)</ul>
|
|
<b><a name="DB_LOCK_IWR">DB_LOCK_IWR</a></b><ul compact><li>intention to read and write (shared)</ul>
|
|
<br>
|
|
<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.</p></ul>
|
|
<b>const Dbt <a name="obj">obj</a>;</b><ul compact><li>An untyped byte string that specifies the object to be locked or
|
|
released. Applications using the locking subsystem directly while also
|
|
doing locking via the Berkeley DB access methods must take care not to
|
|
inadvertently lock objects that happen to be equal to the unique file
|
|
IDs used to lock files. See <a href="../ref/lock/am_conv.html">Access
|
|
method locking conventions</a> for more information.</ul>
|
|
<b>u_int32_t timeout;</b><ul compact><li>The lock timeout value.</ul>
|
|
<br></ul>
|
|
<b>nlist</b><ul compact><li>The <b>nlist</b> parameter specifies the number of elements in the
|
|
<b>list</b> array.</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DbEnv::lock_vec method
|
|
may fail and throw
|
|
<a href="../api_cxx/except_class.html">DbException</a>,
|
|
encapsulating one of the following non-zero errors, or return one of
|
|
the following non-zero errors:</p>
|
|
<br>
|
|
<b>EINVAL</b><ul compact><li>An
|
|
invalid flag value or parameter was specified.</ul>
|
|
<br>
|
|
<p>If a transactional database environment operation was selected to
|
|
resolve a deadlock, the DbEnv::lock_vec method will fail and
|
|
either return <a href="../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or
|
|
throw a <a href="../api_cxx/deadlock_class.html">DbDeadlockException</a> exception.</p>
|
|
<p>If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable
|
|
to grant a lock in the allowed time, the DbEnv::lock_vec method will fail and
|
|
either return <a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or
|
|
throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p>
|
|
<p>If the <a href="../api_cxx/lock_vec.html#DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a> flag or lock timers were configured and the lock could not be granted before the wait-time expired,
|
|
the DbEnv::lock_vec method will fail and
|
|
either return DB_LOCK_NOTGRANTED or
|
|
throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p>
|
|
<p>If the maximum number of locks has been reached, the DbEnv::lock_vec method will fail and
|
|
either return ENOMEM or
|
|
throw a DbMemoryException.</p>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_cxx/env_class.html">DbEnv</a>, <a href="../api_cxx/lock_class.html">DbLock</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_cxx/lock_list.html">Locking Subsystem and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|