1<!--$Id: lock_vec.so,v 10.70 2007/10/26 15:01:06 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DB_ENV->lock_vec</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DB_ENV->lock_vec</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db.h> 23<p> 24int 25DB_ENV->lock_vec(DB_ENV *env, u_int32_t locker, u_int32_t flags, 26 DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DB_ENV->lock_vec</b> 30<p>The DB_ENV->lock_vec method atomically obtains and releases one or more locks 31from the lock table. The DB_ENV->lock_vec method is intended to support 32acquisition or trading of multiple locks under one lock table semaphore, 33as is needed for lock coupling or in multigranularity locking for lock 34escalation.</p> 35<p>If any of the requested locks cannot be acquired, or any of the locks to 36be released cannot be released, the operations before the failing 37operation are guaranteed to have completed successfully, and 38DB_ENV->lock_vec returns a non-zero value. In addition, if 39<b>elistp</b> is not NULL, it is set to point to the DB_LOCKREQ entry 40that was being processed when the error occurred.</p> 41<p>Unless otherwise specified, the DB_ENV->lock_vec method 42returns a non-zero error value on failure 43and 0 on success. 44</p> 45<b>Parameters</b> <br> 46 <b>elistp</b><ul compact><li>If an error occurs, and the <b>elistp</b> parameter is non-NULL, it 47is set to point to the DB_LOCKREQ entry that was being processed when 48the error occurred.</ul> 49 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or 50the following value: 51<br> 52<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 53an existing lock, 54return DB_LOCK_NOTGRANTED immediately instead of waiting 55for the lock to become available. In this case, if non-NULL, 56<b>elistp</b> identifies the request that was not granted. 57</ul> 58<br></ul> 59 <b>locker</b><ul compact><li>The <b>locker</b> parameter is an unsigned 32-bit integer quantity. It 60represents the entity requesting or releasing the lock.</ul> 61 <b>list</b><ul compact><li>The <b>list</b> array provided to DB_ENV->lock_vec is typedef'd as 62DB_LOCKREQ. 63<p>To ensure compatibility with future releases of Berkeley DB, all 64fields of the DB_LOCKREQ structure that are not explicitly set should 65be initialized to 0 before the first time the structure is used. Do 66this by declaring the structure external or static, or by calling 67<b>memset</b>(3).</p> 68<p>A DB_LOCKREQ structure has at least the following fields:</p> 69<br> 70<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 71following values:</ul> 72<br> 73<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> 74structure fields, for the specified <b>locker</b>. Upon return from 75DB_ENV->lock_vec, if the <b>lock</b> field is non-NULL, a reference 76to the acquired lock is stored there. (This reference is invalidated 77by any call to DB_ENV->lock_vec or <a href="../api_c/lock_put.html">DB_ENV->lock_put</a> that releases the 78lock.)</ul> 79<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> 80structure field overrides any previously specified timeout value for 81this lock. A value of 0 turns off any previously specified timeout.</ul> 82<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. 83The <b>locker</b> parameter, and <b>mode</b> and <b>obj</b> fields 84are ignored.</ul> 85<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 86<b>lock</b>, <b>mode</b>, and <b>obj</b> structure fields are 87ignored. Locks acquired in operations performed by the current call to 88DB_ENV->lock_vec which appear before the DB_LOCK_PUT_ALL 89operation are released; those acquired in operations appearing after 90the DB_LOCK_PUT_ALL operation are not released.</ul> 91<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> 92parameter and the <b>lock</b> and <b>mode</b> structure fields are 93ignored. Locks acquired in operations performed by the current call to 94DB_ENV->lock_vec that appear before the DB_LOCK_PUT_OBJ 95operation are released; those acquired in operations appearing after the 96DB_LOCK_PUT_OBJ operation are not released.</ul> 97<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 98database environment has not configured automatic deadlock detection, 99the transaction will timeout the next time deadlock detection is 100performed. As transactions acquire locks on behalf of a single locker 101ID, timing out the locker ID associated with a transaction will time 102out the transaction itself.</ul> 103<br> 104<b>DB_LOCK <a name="lock">lock</a>;</b><ul compact><li>A lock reference.</ul> 105<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. 106When using the default lock conflict matrix, <b>mode</b> must be set to one 107of the following values: 108<br> 109<b><a name="DB_LOCK_READ">DB_LOCK_READ</a></b><ul compact><li>read (shared)</ul> 110<b><a name="DB_LOCK_WRITE">DB_LOCK_WRITE</a></b><ul compact><li>write (exclusive)</ul> 111<b><a name="DB_LOCK_IWRITE">DB_LOCK_IWRITE</a></b><ul compact><li>intention to write (shared)</ul> 112<b><a name="DB_LOCK_IREAD">DB_LOCK_IREAD</a></b><ul compact><li>intention to read (shared)</ul> 113<b><a name="DB_LOCK_IWR">DB_LOCK_IWR</a></b><ul compact><li>intention to read and write (shared)</ul> 114<br> 115<p>See <a href="../api_c/env_set_lk_conflicts.html">DB_ENV->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> 116<b>const DBT <a name="obj">obj</a>;</b><ul compact><li>An untyped byte string that specifies the object to be locked or 117released. Applications using the locking subsystem directly while also 118doing locking via the Berkeley DB access methods must take care not to 119inadvertently lock objects that happen to be equal to the unique file 120IDs used to lock files. See <a href="../ref/lock/am_conv.html">Access 121method locking conventions</a> for more information.</ul> 122<b>u_int32_t timeout;</b><ul compact><li>The lock timeout value.</ul> 123<br></ul> 124 <b>nlist</b><ul compact><li>The <b>nlist</b> parameter specifies the number of elements in the 125<b>list</b> array.</ul> 126<br> 127<br><b>Errors</b> 128<p>The DB_ENV->lock_vec method 129may fail and return one of the following non-zero errors:</p> 130<br> 131<b>DB_LOCK_DEADLOCK</b><ul compact><li>A transactional database environment operation was selected to resolve 132a deadlock.</ul> 133<b>DB_LOCK_NOTGRANTED</b><ul compact><li>A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable 134to grant a lock in the allowed time.</ul> 135<br> 136<br> 137<b>DB_LOCK_NOTGRANTED</b><ul compact><li>The <a href="../api_c/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.</ul> 138<br> 139<br> 140<b>EINVAL</b><ul compact><li>An 141invalid flag value or parameter was specified.</ul> 142<br> 143<br> 144<b>ENOMEM</b><ul compact><li>The maximum number of locks has been reached.</ul> 145<br> 146<hr size=1 noshade> 147<br><b>Class</b> 148<a href="../api_c/env_class.html">DB_ENV</a>, <a href="../api_c/lock_class.html">DB_LOCK</a> 149<br><b>See Also</b> 150<a href="../api_c/lock_list.html">Locking Subsystem and Related Methods</a> 151</tt> 152<table width="100%"><tr><td><br></td><td align=right> 153<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 154</td></tr></table> 155<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 156</body> 157</html> 158
