1<!--Copyright 1999,2008 Oracle. All rights reserved.--> 2<html> 3<head> 4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5 <meta name="GENERATOR" content="Mozilla/4.75 [en] (X11; U; Linux 2.2.16-22 i686) [Netscape]"> 6</head> 7<body> 8 9<h2> 10<a NAME="Locking Commands"></a>Locking Commands</h2> 11Most locking commands work with the environment handle. However, 12when a user gets a lock we create a new lock handle that they then use 13with in a similar manner to all the other handles to release the lock. 14We present the general locking functions first, and then those that manipulate 15locks. 16<p><b>> <env> lock_detect [default|oldest|youngest|random]</b> 17<p>This command runs the deadlock detector. It directly translates 18to the <a href="/docs/api_c/lock_detect.html">lock_detect</a> DB call. 19It returns either a 0 (for success), a DB error message or it throws a 20Tcl error with a system message. The first argument sets the policy 21for deadlock as follows: 22<ul> 23<li> 24<b>default</b> selects the DB_LOCK_DEFAULT policy for default detection 25(default if not specified)</li> 26 27<li> 28<b>oldest </b>selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock</li> 29 30<li> 31<b>random</b> selects DB_LOCK_RANDOM to abort a random locker on a deadlock</li> 32 33<li> 34<b>youngest</b> selects DB_LOCK_YOUNGEST to abort the youngest locker on 35a deadlock</li> 36</ul> 37 38<hr WIDTH="100%"> 39<br><b>> <env> lock_stat</b> 40<p>This command returns a list of name/value pairs where the names correspond 41to the C-structure field names of DB_LOCK_STAT and the values are the data 42returned. This command is a direct translation of the <a href="/docs/api_c/lock_stat.html">lock_stat</a> 43DB call. 44<hr WIDTH="100%"> 45<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id</b> 46<p>This command returns a unique locker ID value. It directly translates 47to the <a href="/docs/api_c/lock_id.html">lock_id</a> DB call. 48<br> 49<hr WIDTH="100%"> 50<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id_free </b><i>locker</i> 51<p>This command frees the locker allockated by the lock_id call. It directly 52translates to the <a href="/docs/api_c/lock_id.html">lock_id_free 53</a>DB 54call. 55<hr WIDTH="100%"> 56<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id_set </b><i>current 57max</i> 58<p>This is a diagnostic command to set the locker id that will get 59allocated next and the maximum id that 60<br>will trigger the id reclaim algorithm. 61<hr WIDTH="100%"> 62<br><a NAME="> <env> lock_get"></a><b>> <env> lock_get [-nowait]<i>lockmode 63locker obj</i></b> 64<p>This command gets a lock. It will invoke the <a href="/docs/api_c/lock_get.html">lock_get</a> 65function. After it successfully gets a handle to a lock, we bind 66it to a new Tcl command of the form <b><i>$env.lockX</i></b>, where X is 67an integer starting at 0 (e.g. <b>$env.lock0, $env.lock1, </b>etc). 68We use the <i>Tcl_CreateObjCommand()</i> to create the top level locking 69command function. It is through this handle that the user can release 70the lock. Internally, the handle we get back from DB will be stored 71as the <i>ClientData</i> portion of the new command set so that future 72locking calls will have that handle readily available. 73<p>The arguments are: 74<ul> 75<li> 76<b><i>locker</i></b> specifies the locker ID returned from the <a href="#> <env> lock_id">lock_id</a> 77command</li> 78 79<li> 80<b><i>obj</i></b> specifies an object to lock</li> 81 82<li> 83the <b><i>lock mode</i></b> is specified as one of the following:</li> 84 85<ul> 86<li> 87<b>ng </b>specifies DB_LOCK_NG for not granted (always 0)</li> 88 89<li> 90<b>read</b> specifies DB_LOCK_READ for a read (shared) lock</li> 91 92<li> 93<b>write</b> specifies DB_LOCK_WRITE for an exclusive write lock</li> 94 95<li> 96<b>iwrite </b>specifies DB_LOCK_IWRITE for intent for exclusive write lock</li> 97 98<li> 99<b>iread </b>specifies DB_LOCK_IREAD for intent for shared read lock</li> 100 101<li> 102<b>iwr </b>specifies DB_LOCK_IWR for intent for eread and write lock</li> 103</ul> 104 105<li> 106<b>-nowait</b> selects the DB_LOCK_NOWAIT to indicate that we do not want 107to wait on the lock</li> 108</ul> 109 110<hr WIDTH="100%"> 111<br><b>> <lock> put</b> 112<p>This command releases the lock referenced by the command. It is 113a direct translation of the <a href="/docs/api_c/lock_put.html">lock_put</a> 114function. It returns either a 0 (for success), a DB error message 115or it throws a Tcl error with a system message. Additionally, since 116the handle is no longer valid, we will call 117<i>Tcl_DeleteCommand() 118</i>so 119that further uses of the handle will be dealt with properly by Tcl itself. 120<br> 121<hr WIDTH="100%"> 122<br><a NAME="> <env> lock_vec"></a><b>> <env> lock_vec [-nowait] <i>locker 123</i>{get|put|put_all|put_obj 124[<i>obj</i>] [<i>lockmode</i>] [<i>lock</i>]} ...</b> 125<p>This command performs a series of lock calls. It is a direct translation 126of the <a href="/docs/api_c/lock_vec.html">lock_vec</a> function. 127This command will return a list of the return values from each operation 128specified in the argument list. For the 'put' operations the entry 129in the return value list is either a 0 (for success) or an error. 130For the 'get' operation, the entry is the lock widget handle, <b>$env.lockN</b> 131(as described above in <a href="#> <env> lock_get"><env> lock_get</a>) 132or an error. If an error occurs, the return list will contain the 133return values for all the successful operations up the erroneous one and 134the error code for that operation. Subsequent operations will be 135ignored. 136<p>As for the other operations, if we are doing a 'get' we will create 137the commands and if we are doing a 'put' we will have to delete the commands. 138Additionally, we will have to do this after the call to the DB lock_vec 139and iterate over the results, creating and/or deleting Tcl commands. 140It is possible that we may return a lock widget from a get operation that 141is considered invalid, if, for instance, there was a <b>put_all</b> operation 142performed later in the vector of operations. The arguments are: 143<ul> 144<li> 145<b><i>locker</i></b> specifies the locker ID returned from the <a href="#> <env> lock_id">lock_id</a> 146command</li> 147 148<li> 149<b>-nowait</b> selects the DB_LOCK_NOWAIT to indicate that we do not want 150to wait on the lock</li> 151 152<li> 153the lock vectors are tuple consisting of {an operation, lock object, lock 154mode, lock handle} where what is required is based on the operation desired:</li> 155 156<ul> 157<li> 158<b>get</b> specifes DB_LOCK_GET to get a lock. Requires a tuple <b>{get 159<i>objmode</i>} 160</b>where 161<b><i>mode</i></b> 162is:</li> 163 164<ul> 165<li> 166<b>ng </b>specifies DB_LOCK_NG for not granted (always 0)</li> 167 168<li> 169<b>read</b> specifies DB_LOCK_READ for a read (shared) lock</li> 170 171<li> 172<b>write</b> specifies DB_LOCK_WRITE for an exclusive write lock</li> 173 174<li> 175<b>iwrite </b>specifies DB_LOCK_IWRITE for intent for exclusive write lock</li> 176 177<li> 178<b>iread </b>specifies DB_LOCK_IREAD for intent for shared read lock</li> 179 180<li> 181<b>iwr </b>specifies DB_LOCK_IWR for intent for eread and write lock</li> 182</ul> 183 184<li> 185<b>put</b> specifies DB_LOCK_PUT to release a <b><i>lock</i></b>. 186Requires a tuple <b>{put <i>lock}</i></b></li> 187 188<li> 189<b>put_all </b>specifies DB_LOCK_PUT_ALL to release all locks held by <b><i>locker</i></b>. 190Requires a tuple <b>{put_all}</b></li> 191 192<li> 193<b>put_obj</b> specifies DB_LOCK_PUT_OBJ to release all locks held by <b><i>locker</i></b> 194associated with the given <b><i>obj</i></b>. Requires a tuple <b>{put_obj 195<i>obj}</i></b></li> 196</ul> 197</ul> 198 199<hr WIDTH="100%"> 200<br><a NAME="> <env> lock_vec"></a><b>> <env> lock_timeout <i>timeout</i></b> 201<p>This command sets the lock timeout for all future locks in this environment. 202The timeout is in micorseconds. 203<br> 204<br> 205</body> 206</html> 207