diff options
Diffstat (limited to 'bdb/tcl/docs/lock.html')
| -rw-r--r-- | bdb/tcl/docs/lock.html | 308 |
1 files changed, 164 insertions, 144 deletions
diff --git a/bdb/tcl/docs/lock.html b/bdb/tcl/docs/lock.html index 87a20e9a6bf..d65142b798b 100644 --- a/bdb/tcl/docs/lock.html +++ b/bdb/tcl/docs/lock.html @@ -1,187 +1,207 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> -<HTML> -<HEAD> - <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> - <META NAME="GENERATOR" CONTENT="Mozilla/4.08 [en] (X11; I; FreeBSD 2.2.8-19990120-SNAP i386) [Netscape]"> -</HEAD> -<BODY> - -<H2> -<A NAME="Locking Commands"></A>Locking Commands</H2> +<!--Copyright 1999-2002 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.75 [en] (X11; U; Linux 2.2.16-22 i686) [Netscape]"> +</head> +<body> + +<h2> +<a NAME="Locking Commands"></a>Locking Commands</h2> Most locking commands work with the environment handle. However, when a user gets a lock we create a new lock handle that they then use with in a similar manner to all the other handles to release the lock. We present the general locking functions first, and then those that manipulate locks. -<P><B>> <env> lock_detect [-lock_conflict] [default|oldest|youngest|random]</B> -<P>This command runs the deadlock detector. It directly translates -to the <A HREF="../../docs/api_c/lock_detect.html">lock_detect</A> DB call. +<p><b>> <env> lock_detect [default|oldest|youngest|random]</b> +<p>This command runs the deadlock detector. It directly translates +to the <a href="../../docs/api_c/lock_detect.html">lock_detect</a> DB call. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message. The first argument sets the policy for deadlock as follows: -<UL> -<LI> -<B>default</B> selects the DB_LOCK_DEFAULT policy for default detection -(default if not specified)</LI> - -<LI> -<B>oldest </B>selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock</LI> - -<LI> -<B>random</B> selects DB_LOCK_RANDOM to abort a random locker on a deadlock</LI> - -<LI> -<B>youngest</B> selects DB_LOCK_YOUNGEST to abort the youngest locker on -a deadlock</LI> -</UL> -The second argument, <B>-lock_conflict</B>, selects the DB_LOCK_CONFLICT -flag to only run the detector if a lock conflict has occurred since the -last time the detector was run. -<HR WIDTH="100%"> -<BR><B>> <env> lock_stat</B> -<P>This command returns a list of name/value pairs where the names correspond +<ul> +<li> +<b>default</b> selects the DB_LOCK_DEFAULT policy for default detection +(default if not specified)</li> + +<li> +<b>oldest </b>selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock</li> + +<li> +<b>random</b> selects DB_LOCK_RANDOM to abort a random locker on a deadlock</li> + +<li> +<b>youngest</b> selects DB_LOCK_YOUNGEST to abort the youngest locker on +a deadlock</li> +</ul> + +<hr WIDTH="100%"> +<br><b>> <env> lock_stat</b> +<p>This command returns a list of name/value pairs where the names correspond to the C-structure field names of DB_LOCK_STAT and the values are the data -returned. This command is a direct translation of the <A HREF="../../docs/api_c/lock_stat.html">lock_stat</A> +returned. This command is a direct translation of the <a href="../../docs/api_c/lock_stat.html">lock_stat</a> DB call. -<HR WIDTH="100%"> -<BR><A NAME="> <env> lock_id"></A><B>> <env> lock_id</B> -<P>This command returns a unique locker ID value. It directly translates -to the <A HREF="../../docs/api_c/lock_id.html">lock_id</A> DB call. -<HR WIDTH="100%"> -<BR><A NAME="> <env> lock_get"></A><B>> <env> lock_get [-nowait]<I>lockmode -locker obj</I></B> -<P>This command gets a lock. It will invoke the <A HREF="../../docs/api_c/lock_get.html">lock_get</A> +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id</b> +<p>This command returns a unique locker ID value. It directly translates +to the <a href="../../docs/api_c/lock_id.html">lock_id</a> DB call. +<br> +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id_free </b><i>locker</i> +<p>This command frees the locker allockated by the lock_id call. It directly +translates to the <a href="../../docs/api_c/lock_id.html">lock_id_free +</a>DB +call. +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_id"></a><b>> <env> lock_id_set </b><i>current +max</i> +<p>This is a diagnostic command to set the locker id that will get +allocated next and the maximum id that +<br>will trigger the id reclaim algorithm. +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_get"></a><b>> <env> lock_get [-nowait]<i>lockmode +locker obj</i></b> +<p>This command gets a lock. It will invoke the <a href="../../docs/api_c/lock_get.html">lock_get</a> function. After it successfully gets a handle to a lock, we bind -it to a new Tcl command of the form <B><I>$env.lockX</I></B>, where X is -an integer starting at 0 (e.g. <B>$env.lock0, $env.lock1, </B>etc). -We use the <I>Tcl_CreateObjCommand()</I> to create the top level locking +it to a new Tcl command of the form <b><i>$env.lockX</i></b>, where X is +an integer starting at 0 (e.g. <b>$env.lock0, $env.lock1, </b>etc). +We use the <i>Tcl_CreateObjCommand()</i> to create the top level locking command function. It is through this handle that the user can release the lock. Internally, the handle we get back from DB will be stored -as the <I>ClientData</I> portion of the new command set so that future +as the <i>ClientData</i> portion of the new command set so that future locking calls will have that handle readily available. -<P>The arguments are: -<UL> -<LI> -<B><I>locker</I></B> specifies the locker ID returned from the <A HREF="#> <env> lock_id">lock_id</A> -command</LI> +<p>The arguments are: +<ul> +<li> +<b><i>locker</i></b> specifies the locker ID returned from the <a href="#> <env> lock_id">lock_id</a> +command</li> -<LI> -<B><I>obj</I></B> specifies an object to lock</LI> +<li> +<b><i>obj</i></b> specifies an object to lock</li> -<LI> -the <B><I>lock mode</I></B> is specified as one of the following:</LI> +<li> +the <b><i>lock mode</i></b> is specified as one of the following:</li> -<UL> -<LI> -<B>ng </B>specifies DB_LOCK_NG for not granted (always 0)</LI> +<ul> +<li> +<b>ng </b>specifies DB_LOCK_NG for not granted (always 0)</li> -<LI> -<B>read</B> specifies DB_LOCK_READ for a read (shared) lock</LI> +<li> +<b>read</b> specifies DB_LOCK_READ for a read (shared) lock</li> -<LI> -<B>write</B> specifies DB_LOCK_WRITE for an exclusive write lock</LI> +<li> +<b>write</b> specifies DB_LOCK_WRITE for an exclusive write lock</li> -<LI> -<B>iwrite </B>specifies DB_LOCK_IWRITE for intent for exclusive write lock</LI> +<li> +<b>iwrite </b>specifies DB_LOCK_IWRITE for intent for exclusive write lock</li> -<LI> -<B>iread </B>specifies DB_LOCK_IREAD for intent for shared read lock</LI> +<li> +<b>iread </b>specifies DB_LOCK_IREAD for intent for shared read lock</li> -<LI> -<B>iwr </B>specifies DB_LOCK_IWR for intent for eread and write lock</LI> -</UL> +<li> +<b>iwr </b>specifies DB_LOCK_IWR for intent for eread and write lock</li> +</ul> -<LI> -<B>-nowait</B> selects the DB_LOCK_NOWAIT to indicate that we do not want -to wait on the lock</LI> -</UL> +<li> +<b>-nowait</b> selects the DB_LOCK_NOWAIT to indicate that we do not want +to wait on the lock</li> +</ul> -<HR WIDTH="100%"> -<BR><B>> <lock> put</B> -<P>This command releases the lock referenced by the command. It is -a direct translation of the <A HREF="../../docs/api_c/lock_put.html">lock_put</A> +<hr WIDTH="100%"> +<br><b>> <lock> put</b> +<p>This command releases the lock referenced by the command. It is +a direct translation of the <a href="../../docs/api_c/lock_put.html">lock_put</a> function. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message. Additionally, since the handle is no longer valid, we will call -<I>Tcl_DeleteCommand() -</I>so +<i>Tcl_DeleteCommand() +</i>so that further uses of the handle will be dealt with properly by Tcl itself. -<BR> -<HR WIDTH="100%"> -<BR><A NAME="> <env> lock_vec"></A><B>> <env> lock_vec [-nowait] <I>locker -</I>{get|put|put_all|put_obj -[<I>obj</I>] [<I>lockmode</I>] [<I>lock</I>]} ...</B> -<P>This command performs a series of lock calls. It is a direct translation -of the <A HREF="../../docs/api_c/lock_vec.html">lock_vec</A> function. +<br> +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_vec"></a><b>> <env> lock_vec [-nowait] <i>locker +</i>{get|put|put_all|put_obj +[<i>obj</i>] [<i>lockmode</i>] [<i>lock</i>]} ...</b> +<p>This command performs a series of lock calls. It is a direct translation +of the <a href="../../docs/api_c/lock_vec.html">lock_vec</a> function. This command will return a list of the return values from each operation specified in the argument list. For the 'put' operations the entry in the return value list is either a 0 (for success) or an error. -For the 'get' operation, the entry is the lock widget handle, <B>$env.lockN</B> -(as described above in <A HREF="#> <env> lock_get"><env> lock_get</A>) +For the 'get' operation, the entry is the lock widget handle, <b>$env.lockN</b> +(as described above in <a href="#> <env> lock_get"><env> lock_get</a>) or an error. If an error occurs, the return list will contain the return values for all the successful operations up the erroneous one and the error code for that operation. Subsequent operations will be ignored. -<P>As for the other operations, if we are doing a 'get' we will create +<p>As for the other operations, if we are doing a 'get' we will create the commands and if we are doing a 'put' we will have to delete the commands. Additionally, we will have to do this after the call to the DB lock_vec and iterate over the results, creating and/or deleting Tcl commands. It is possible that we may return a lock widget from a get operation that -is considered invalid, if, for instance, there was a <B>put_all</B> operation +is considered invalid, if, for instance, there was a <b>put_all</b> operation performed later in the vector of operations. The arguments are: -<UL> -<LI> -<B><I>locker</I></B> specifies the locker ID returned from the <A HREF="#> <env> lock_id">lock_id</A> -command</LI> +<ul> +<li> +<b><i>locker</i></b> specifies the locker ID returned from the <a href="#> <env> lock_id">lock_id</a> +command</li> -<LI> -<B>-nowait</B> selects the DB_LOCK_NOWAIT to indicate that we do not want -to wait on the lock</LI> +<li> +<b>-nowait</b> selects the DB_LOCK_NOWAIT to indicate that we do not want +to wait on the lock</li> -<LI> +<li> the lock vectors are tuple consisting of {an operation, lock object, lock -mode, lock handle} where what is required is based on the operation desired:</LI> - -<UL> -<LI> -<B>get</B> specifes DB_LOCK_GET to get a lock. Requires a tuple <B>{get -<I>obj</I> -<I>mode</I>} -</B>where -<B><I>mode</I></B> -is:</LI> - -<UL> -<LI> -<B>ng </B>specifies DB_LOCK_NG for not granted (always 0)</LI> - -<LI> -<B>read</B> specifies DB_LOCK_READ for a read (shared) lock</LI> - -<LI> -<B>write</B> specifies DB_LOCK_WRITE for an exclusive write lock</LI> - -<LI> -<B>iwrite </B>specifies DB_LOCK_IWRITE for intent for exclusive write lock</LI> - -<LI> -<B>iread </B>specifies DB_LOCK_IREAD for intent for shared read lock</LI> - -<LI> -<B>iwr </B>specifies DB_LOCK_IWR for intent for eread and write lock</LI> -</UL> - -<LI> -<B>put</B> specifies DB_LOCK_PUT to release a <B><I>lock</I></B>. -Requires a tuple <B>{put <I>lock}</I></B></LI> - -<LI> -<B>put_all </B>specifies DB_LOCK_PUT_ALL to release all locks held by <B><I>locker</I></B>. -Requires a tuple <B>{put_all}</B></LI> - -<LI> -<B>put_obj</B> specifies DB_LOCK_PUT_OBJ to release all locks held by <B><I>locker</I></B> -associated with the given <B><I>obj</I></B>. Requires a tuple <B>{put_obj -<I>obj</I>}</B></LI> -</UL> -</UL> +mode, lock handle} where what is required is based on the operation desired:</li> + +<ul> +<li> +<b>get</b> specifes DB_LOCK_GET to get a lock. Requires a tuple <b>{get +<i>objmode</i>} +</b>where +<b><i>mode</i></b> +is:</li> + +<ul> +<li> +<b>ng </b>specifies DB_LOCK_NG for not granted (always 0)</li> + +<li> +<b>read</b> specifies DB_LOCK_READ for a read (shared) lock</li> + +<li> +<b>write</b> specifies DB_LOCK_WRITE for an exclusive write lock</li> + +<li> +<b>iwrite </b>specifies DB_LOCK_IWRITE for intent for exclusive write lock</li> + +<li> +<b>iread </b>specifies DB_LOCK_IREAD for intent for shared read lock</li> + +<li> +<b>iwr </b>specifies DB_LOCK_IWR for intent for eread and write lock</li> +</ul> + +<li> +<b>put</b> specifies DB_LOCK_PUT to release a <b><i>lock</i></b>. +Requires a tuple <b>{put <i>lock}</i></b></li> + +<li> +<b>put_all </b>specifies DB_LOCK_PUT_ALL to release all locks held by <b><i>locker</i></b>. +Requires a tuple <b>{put_all}</b></li> + +<li> +<b>put_obj</b> specifies DB_LOCK_PUT_OBJ to release all locks held by <b><i>locker</i></b> +associated with the given <b><i>obj</i></b>. Requires a tuple <b>{put_obj +<i>obj}</i></b></li> +</ul> +</ul> + +<hr WIDTH="100%"> +<br><a NAME="> <env> lock_vec"></a><b>> <env> lock_timeout <i>timeout</i></b> +<p>This command sets the lock timeout for all future locks in this environment. +The timeout is in micorseconds. +<br> +<br> +</body> +</html> |