commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From maso...@apache.org
Subject cvs commit: jakarta-commons/transaction/xdocs/locks tutorial.xml
Date Sun, 21 Nov 2004 07:52:27 GMT
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


Mime
View raw message