← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/tcl/docs/lock.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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