ozeigermann 2004/10/31 12:39:57
Modified: transaction/xdocs/locks tutorial.xml
Log:
Made formatting less shitty
Revision Changes Path
1.3 +22 -20 jakarta-commons-sandbox/transaction/xdocs/locks/tutorial.xml
Index: tutorial.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/transaction/xdocs/locks/tutorial.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- tutorial.xml 31 Oct 2004 20:25:59 -0000 1.2
+++ tutorial.xml 31 Oct 2004 20:39:57 -0000 1.3
@@ -60,21 +60,23 @@
block to ban the hazard of deadlocks. Slide does this with a simple
synchronized block, but to have something to show here we will exercise it
with a multi level lock. Such a lock is very simple and is merely
-exclusive, it will look like this:
+exclusive, it will look like this:</p>
<source>
GenericLock exclusive = new new GenericLock("Mutex", 1,
new PrintWriterLogger(new PrintWriter(System.out), "Locking", false));
</source>
+<p>
Now we have a lock called "Mutex" with the highest lock level of
<code>1</code> and a logger that simply writes to stdout. Different
lock levels and their compatibility is a special feature of
<a
href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/locking/GenericLock.html";>GenericLock</a>
and is explained there in detail. As we have one locking level, this
-also is the only level we can possibly acquire causing an exclusive lock:
+also is the only level we can possibly acquire causing an exclusive lock:</p>
<source>
exclusive.acquire("Owner", 1, true, true, Long.MAX_VALUE);
</source>
+<p>
This tries to <a
href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/locking/GenericLock.html#acquire(java.lang.Object,%20int,%20boolean,%20boolean,%20long)">acquire
a lock</a> of level one (=exclusive) for the agent
@@ -90,11 +92,11 @@
<p>Now all requests to fine grained locks will be braced with the
above statement and the <a
href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/locking/GenericLock.html#release(java.lang.Object)">release
-statement</a> after all fine grained locks are acquired:
+statement</a> after all fine grained locks are acquired:</p>
<source>
exclusive.release("Owner");
</source>
-As a single agent ("Owner" in our case) can have at most one lock
+<p>As a single agent ("Owner" in our case) can have at most one lock
level on a lock - only the highest will be effective - no more than
the agent is required as a parameter.
</p>
@@ -102,7 +104,7 @@
<p>Coming to the fain grained locks: Slide puts read and write locks
on resources accessed by WebDAV requests. As we really have no idea
with resources will be accessed until we receive the actual request we
-use a lock manager which looks like this:
+use a lock manager which looks like this:</p>
<source>
public final static READ_LOCK = 1;
public final static WRITE_LOCK = 2;
@@ -111,29 +113,28 @@
new PrintWriterLogger(new PrintWriter(System.out), "Locking", false));
</source>
-Logs are the same as with the generic lock, they go to stdout. Before
-explaining more details, let's see how we get a lock from that manager:
+<p>Logs are the same as with the generic lock, they go to stdout. Before
+explaining more details, let's see how we get a lock from that manager:</p>
<source>
GenericLock lock = (GenericLock) lockManager.atomicGetOrCreateLock("/");
</source>
-This gives us the lock for the resource called "/" which of course is semantically
+<p>This gives us the lock for the resource called "/" which of course is
semantically
associated with the root of Slide's resource tree. The highst lock
level for the lock has been defined to two using the constant
<code>WRITE_LOCK</code>. Besides, it is good practice to use constants for the
lock levels in order to avoid unreadable code. Anyway, this returns a
-lock that might have been created by this statement as well:
+lock that might have been created by this statement as well:</p>
<source>
GenericLock readWrite = new new GenericLock("/", 2,
new PrintWriterLogger(new PrintWriter(System.out), "Locking", false));
</source>
-However, if we ask the lock manager for this lock the next time it
+<p>However, if we ask the lock manager for this lock the next time it
will not create a new lock, but will return the one created first
- preserving all lock levels already set. The assertion that all this
will be done atomically is very important for correctness and because
of this is reflected in the name of the method.
-
</p>
<p>The locks created by the above lock manager have two levels where
@@ -145,18 +146,18 @@
locks as a there is no reason not to allow two GET requests to the
same resource at the same time. However, you should not allow a PUT
and a GET request to the same resource at the same time or even two PUT
-requests. This means that none of the below statements will block
+requests. This means that none of the below statements will block</p>
<source>
readWrite.acquire("request1", READ_LOCK, true, true, Long.MAX_VALUE);
readWrite.acquire("request2", READ_LOCK, true, true, Long.MAX_VALUE);
</source>
+<p>
which would mean two requests called "request1" and "request2" can
read the root resource at the same time. Without releasing both of the
-above locks the following write request will be blocked:
+above locks the following write request will be blocked:</p>
<source>
readWrite.acquire("request3", WRITE_LOCK, true, true, Long.MAX_VALUE);
</source>
-</p>
</subsection>
@@ -187,7 +188,7 @@
in or case: we need two read/write locks!</p>
<p>
-Now a search request would try to acquire those locks before it executes:
+Now a search request would try to acquire those locks before it executes:</p>
<source>
public final static SHARED_LOCK = 1;
public final static EXCLUSIVE_LOCK = 2;
@@ -195,13 +196,14 @@
searchLock.acquire("search request", SHARED_LOCK, true, true, Long.MAX_VALUE);
writeLock.acquire("search request", EXCLUSIVE_LOCK, true, true, Long.MAX_VALUE);
</source>
-Note that we now call lock level one SHARED and lock level two
+<p>Note that we now call lock level one SHARED and lock level two
EXCLUSIVE instead of READ and WRITE as it fits the semantics of these
-operations better. Any write request will call these statements
+operations better. Any write request will call these statements</p>
<source>
writeLock.acquire("write request", SHARED_LOCK, true, true, Long.MAX_VALUE);
searchLock.acquire("write request", EXCLUSIVE_LOCK, true, true, Long.MAX_VALUE);
</source>
+<p>
as the counter part of the above.
</p>
@@ -222,21 +224,21 @@
generic lock not to consider lock levels acquired by other locking
agents - such as the search method - for compatibility calculation if
they have the same lock level you desire. This results in the
-following code which is the final version:
+following code which is the final version:</p>
<source>
searchLock.acquire("search request", SHARED_LOCK, true, true, Long.MAX_VALUE);
writeLock.acquire("search request", EXCLUSIVE_LOCK, true,
GenericLock.COMPATIBILITY_REENTRANT_AND_SUPPORT, Long.MAX_VALUE);
</source>
-and
+<p>and</p>
<source>
writeLock.acquire("write request", SHARED_LOCK, true, true, Long.MAX_VALUE);
searchLock.acquire("write request", EXCLUSIVE_LOCK, true,
GenericLock.COMPATIBILITY_REENTRANT_AND_SUPPORT, Long.MAX_VALUE);
</source>
-As much for our short round trip. More information about this additional
compatibility can be found <a
+<p>As much for our short round trip. More information about this additional
compatibility can be found <a
href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/locking/GenericLock.html#acquire(java.lang.Object,%20int,%20boolean,%20int,%20long)">here</a>.
If you still need more turn
to the mailing list, get through the Javadocs and as the last resort through
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
