commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Oliver Zeigermann <oliver.zeigerm...@gmail.com>
Subject Re: cvs commit: jakarta-commons/transaction/xdocs/locks tutorial.xml
Date Sun, 21 Nov 2004 16:51:34 GMT
Hey, great, this is almost readable now ;)

Oliver

On 21 Nov 2004 07:52:27 -0000, masonjm@apache.org <masonjm@apache.org> wrote:
> masonjm     2004/11/20 23:52:27
> 
>   Modified:    transaction/xdocs/locks tutorial.xml
>   Log:
>   Minor grammar and spelling fixes.
> 
>   Revision  Changes    Path
>   1.3       +39 -39    jakarta-commons/transaction/xdocs/locks/tutorial.xml
> 
>   Index: tutorial.xml
>   ===================================================================
>   RCS file: /home/cvs/jakarta-commons/transaction/xdocs/locks/tutorial.xml,v
>   retrieving revision 1.2
>   retrieving revision 1.3
>   diff -u -r1.2 -r1.3
>   --- tutorial.xml      19 Nov 2004 23:58:46 -0000      1.2
>   +++ tutorial.xml      21 Nov 2004 07:52:27 -0000      1.3
>   @@ -20,12 +20,12 @@
>    lock</a> and specific implementations. There is a <a
>    href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html">generic
>    implementation</a> of a multi level lock with a subtle, yet simple
>   -compatibility mechanism. This mechanism allows to implement quite a
>   +compatibility mechanism. This mechanism allows for implementing quite a
>    number of different lock types such as a read write lock which is
>    <a
>    href="../apidocs/org/apache/commons/transaction/locking/ReadWriteLock.html">provided
>   -for covenience</a>, although very easy to implement. As already
>   -<a href="index.html">exlained</a> in the locking agent can be any Java
>   +for covenience</a>. As explained
>   +<a href="index.html">earlier</a> the locking agent can be any Java
>    object. Have a look at the simple <a
>    href="../apidocs/org/apache/commons/transaction/locking/ReadWriteLock.html#acquireRead(java.lang.Object,%20long)">
>    method for acquiring a lock for read access</a> as a reference.</p>
>   @@ -39,7 +39,7 @@
>    href="../apidocs/org/apache/commons/transaction/locking/LockManager.html#atomicGetOrCreateLock(java.lang.Object)">important
>    method</a> is for either creating a non existing lock in a specified
>    resource or retrieving it if it was created before. It is important to
>   -make this atomically so there is no chance of acciently creating more
>   +make this atomic so there is no chance of accidently creating more
>    than one lock for a single resource.</p>
>    <p><em>The whole trick is to have at
>    most one lock for a resource and have different compatible lock levels
>   @@ -50,23 +50,23 @@
>    <subsection name="Example: Fine grained locks in Jakarta Slide">
> 
>    <p>Lets get to the first example which is how Jakarta Slide handles
>   -fine grained locking in its WebDAV layer. Slide can store resources to
>   -all kinds of stores which most likely have locks for consistency as
>   -well. However, there is this generic locking to be very sure there are
>   -no deadlocks, the behavior is similar for all stores and finally to
>   +fine grained locking in its WebDAV layer. Slide can store resources in
>   +all kinds of stores which most likely will implement their own locks for
>   +consistency. However, Slide has generic locking to be certain there are
>   +no deadlocks, and the behavior is similar for all stores to
>    provide locking for stores that do not have locks of their own. All
>   -locks must be set at the very beginning of a request and release at
>   +locks must be set at the very beginning of a request and released at
>    the end of the request in an atomic
>    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:</p>
>   +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
>   +Now we have a lock called "Mutex" with a 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
>   @@ -80,16 +80,16 @@
>    This tries to <a
>    href="../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
>   -"Owner". Parameters three and four tells the lock that it should block
>   +"Owner". Parameters three and four tell the lock that it should block
>    the current thread if this lock level can not be acquired and that
>   -this lock is reentrant. Reentrant means that the same agant can
>   -require lock levels otherwise incompatible. Finally, there is a
>   +this lock is reentrant. Reentrant means that the same agent can
>   +require lock levels that would be otherwise incompatible. Finally, there is a
>    timeout which is the maximum time the agent will wait for a lock. If a
>    lock still is unavailable after this time the method will return
>   -false. In our case the request will (practically) never time out, we just wait until
>   +false. In our case the request will (practically) never time out; we just wait until
>    we are served.</p>
> 
>   -<p>Now all requests to fine grained locks will be braced with the
>   +<p>Now all requests with fine grained locks will be braced with the
>    above statement and the <a
>    href="../apidocs/org/apache/commons/transaction/locking/GenericLock.html#release(java.lang.Object)">release
>    statement</a> after all fine grained locks are acquired:</p>
>   @@ -103,7 +103,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
>   +which resources will be accessed until we receive the request we
>    use a lock manager which looks like this:</p>
>    <source>
>    public final static READ_LOCK = 1;
>   @@ -113,17 +113,17 @@
>                new PrintWriterLogger(new PrintWriter(System.out), "Locking", false));
>    </source>
> 
>   -<p>Logs are the same as with the generic lock, they go to stdout. Before
>   +<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>
>   -<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
>   +<p>This gives us the lock for the resource called "/" which is semantically
>   +associated with the root of Slide's resource tree. The highest 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:</p>
>   +<code>WRITE_LOCK</code>. It is good practice to use constants for the
>   +lock levels in order to avoid unreadable code. This returns a
>   +lock that could have been created by this statement as well:</p>
> 
>    <source>
>    GenericLock readWrite = new new GenericLock("/", 2,
>   @@ -131,21 +131,21 @@
>    </source>
> 
>    <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
>   +will not create a new lock. Instead it will return the lock 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.
>   +of this it is reflected in the name of the method.
>    </p>
> 
>    <p>The locks created by the above lock manager have two levels where
>   -write is exclusive and read is shared. This means if there is a
>   +the write level is exclusive and the read level is shared. This means if there is
a
>    write lock there can be no read locks and the other way
>    round. However, in the absense of a write lock read locks can happily
>    coexist with other read locks - they are shared - while write locks can not coexist
with
>   -other write locks - they are exclusive. This is very useful for server
>   +other write locks - they are exclusive. This is very useful for webdav server
>    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
>   +and a GET request to the same resource at the same time or two PUT
>    requests. This means that none of the below statements will block</p>
>    <source>
>    readWrite.acquire("request1", READ_LOCK, true, true, Long.MAX_VALUE);
>   @@ -165,15 +165,15 @@
> 
>    <p>In Slide there is a search method that allows you to
>    query for a set of documents that satisfy certain search
>   -conditions. When you execute such a query at least the result
>   +conditions. When you execute such a query the result
>    documents and indices will be touched with read access. As we learned
>    before we need to acquire all locks on the documents accessed before
>    starting the actual request to guarantee correctness and eliminate the
>   -hazard of any deadlock. Of course there is no way to determine which
>   -documents this will be beforehand as this would require anticipate the
>   -result. Effectively, we need a global read lock. Now, while there is a
>   -global read lock no other request must be allowed to write
>   -concurrently. More than one concurrent search request all having a
>   +hazard of deadlocks. Of course there is no way to determine which
>   +documents this will be beforehand as that would require anticipating the
>   +search results. Effectively, we need a global read lock. Now, while there is a
>   +global read lock no other request may be allowed to write
>   +concurrently. More than one concurrent search request having a
>    global read lock would be no problem, but all requests that write in
>    any way must acquire an exclusive write lock. Easy, one could say, so
>    we have a lock with levels READ and WRITE which is a
>   @@ -181,9 +181,9 @@
>    will demolish our fine grained locking mentioned before: writes would
>    now be globally exclusive again. So, what we want from our lock is
>    that an unrestricted number of search requests - in absence of any
>   -write request - may be done concurrently. Additionally, an
>   +write requests - may happen concurrently. Additionally, an
>    unrestricted number of concurrent write requests - in absence of any
>   -search request - should be allowed as well. Sometimes the solution to
>   +search requests - should be allowed as well. Sometimes the solution to
>    a problem becomes obvious as soon as you have written it down - like
>    in or case: we need two read/write locks!</p>
> 
>   @@ -207,7 +207,7 @@
>    as the counter part of the above.
>    </p>
> 
>   -<p>That's it, isn't it? No, it is not. You might have already noticed,
>   +<p>That's it, isn't it? No, it is not. You might have already noticed
>    that nothing has been gained. Now all write methods block each other
>    in the searchLock and all search methods block each other in the
>    writeLock! <em>Sigh</em>! This is not what we wanted, we just wanted
>   @@ -216,7 +216,7 @@
>    <em>compatible</em>. This is tough as the compatibility mechanism of
>    the generic lock is based on the order of the levels and the highest
>    simply is exclusive. Adding another lock level to make the formerly
>   -highest non exclusive would only cause a mess as no one would
>   +highest non-exclusive would only cause a mess as no one would
>    understand anything any more and most important it would still not be
>    compatible to itself. Luckily, next to the additional reentrant compatibility we
>    have already used above there is the so called <code>support</code>
>   @@ -243,7 +243,7 @@
>    <p>As much for our short round trip. More information about this additional
compatibility can be found <a
>    href="../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 the mailing list, go through the Javadocs and as the last resort through
>    the sources ;)
> 
>    </p>
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 
>

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message