<!--$Id: lock_vec.so,v 10.31 2000/12/04 18:05:39 bostic Exp $-->
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
</head>
<body bgcolor=white>
        <a name="2"><!--meow--></a>    
<table><tr valign=top>
<td>
<h1>DbEnv::lock_vec</h1>
</td>
<td width="1%">
<a href="../api_cxx/cxx_index.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>
<h3><pre>
#include &lt;db_cxx.h&gt;
<p>
int
DbEnv::lock_vec(u_int32_t locker, u_int32_t flags,
    DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);
</pre></h3>
<h1>Description</h1>
<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>The <b>locker</b> argument specified to DbEnv::lock_vec is an unsigned
32-bit integer quantity.  It represents the entity requesting or releasing
the lock.
<p>The <b>flags</b> value must be set to 0 or the following value:
<p><dl compact>
<p><dt><a name="DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a><dd>If a lock cannot be immediately granted because the requested lock
conflicts with an existing lock, return instead of waiting for the lock
to become available.
</dl>
<p>The <b>list</b> array provided to DbEnv::lock_vec is typedef'd as
DB_LOCKREQ.  A DB_LOCKREQ structure has at least the following fields,
which must be initialized before calling DbEnv::lock_vec:
<p><dl compact>
<p><dt>lockop_t <a name="op">op</a>;<dd>The operation to be performed, which must be set to one of the
following values:
<p><dl compact>
<p><dt><a name="DB_LOCK_GET">DB_LOCK_GET</a><dd>Get a lock, as defined by the values of <b>locker</b>, <b>obj</b>,
and <b>mode</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">DbLock::put</a> that releases the lock.)
<p><dt><a name="DB_LOCK_PUT">DB_LOCK_PUT</a><dd>The lock referenced by the contents of the <b>lock</b> field is released.
<p><dt><a name="DB_LOCK_PUT_ALL">DB_LOCK_PUT_ALL</a><dd>All locks held by the <b>locker</b> are released.  (Any locks acquired
as a part of the current call to DbEnv::lock_vec that appear after the
DB_LOCK_PUT_ALL entry are not considered for this
operation).
<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 <b>mode</b>
and <b>locker</b> parameters are ignored.  Note that any locks acquired
as a part of the current call to DbEnv::lock_vec that occur before the
DB_LOCK_PUT_OBJ will also be released; those acquired afterwards
will not be released.
</dl>
<p><dt>const Dbt <a name="obj">obj</a>;<dd>An untyped byte string that specifies the object to be locked or released.
<p><dt>const lockmode_t <a name="mode">mode</a>;<dd>The lock mode, used as an index into the environment's lock conflict array.
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 a description of that array.
<p><dt>DB_LOCK <a name="lock">lock</a>;<dd>A lock reference.
</dl>
<p>The <b>nlist</b> argument specifies the number of elements in the
<b>list</b> array.
<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>The DbEnv::lock_vec method may
return or throw an exception encapsulating
one of the following values:
<p><dl compact>
<p><dt><a name="DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a><dd>A lock was requested that could not be immediately granted and the
<b>flag</b> parameter was set to DB_LOCK_NOWAIT.  In this case, if
non-NULL, <b>elistp</b> identifies the request that was not granted.
</dl>
<p>Otherwise, 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.
<h1>Errors</h1>
<p>The DbEnv::lock_vec method may fail and throw an exception or return a non-zero error for the following conditions:
<p><dl compact>
<p><dt>DB_LOCK_DEADLOCK<dd>The operation was selected to resolve a deadlock.
</dl>
<p><dl compact>
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
</dl>
<p><dl compact>
<p><dt>ENOMEM<dd>The maximum number of locks has been reached.
</dl>
<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.
If a catastrophic error has occurred, the DbEnv::lock_vec method may fail and either
return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw an exception encapsulating
<a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, in which case all subsequent Berkeley DB calls will fail
in the same way.
<h3>Classes</h3>
<a href="../api_cxx/dbenv_class.html">DbEnv</a>, <a href="../api_cxx/lock_class.html">DbLock</a>
<h1>See Also</h1>
<a href="../api_cxx/env_set_lk_conflicts.html">DbEnv::set_lk_conflicts</a>,
<a href="../api_cxx/env_set_lk_detect.html">DbEnv::set_lk_detect</a>,
<a href="../api_cxx/env_set_lk_max_locks.html">DbEnv::set_lk_max_locks</a>,
<a href="../api_cxx/env_set_lk_max_lockers.html">DbEnv::set_lk_max_lockers</a>,
<a href="../api_cxx/env_set_lk_max_objects.html">DbEnv::set_lk_max_objects</a>,
<a href="../api_cxx/env_set_lk_max.html">DbEnv::set_lk_max</a>,
<a href="../api_cxx/lock_detect.html">DbEnv::lock_detect</a>,
<a href="../api_cxx/lock_get.html">DbEnv::lock_get</a>,
<a href="../api_cxx/lock_id.html">DbEnv::lock_id</a>,
<a href="../api_cxx/lock_put.html">DbLock::put</a>,
<a href="../api_cxx/lock_stat.html">DbEnv::lock_stat</a>
and
<a href="../api_cxx/lock_vec.html">DbEnv::lock_vec</a>.
</tt>
<table><tr><td><br></td><td width="1%">
<a href="../api_cxx/cxx_index.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><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
</body>
</html>