001: /*
002: * (c) Copyright 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: * All rights reserved.
004: * [See end of file]
005: */
006:
007: /**
008: * A lock.
009: * Critical section support for multithreaed access to a model
010: * within a single JVM. See also transactions support.
011: *
012: * Examples if application code:
013: * <pre>
014: * try {
015: * model.enterCriticalSection(ModelLock.READ) ;
016: * ...
017: * } finally { model.leaveCriticalSection() ; }
018: * </pre>
019: *
020: * Nested locks are provided for:
021: * <pre>
022: * try {
023: * model.enterCriticalSection(ModelLock.WRITE) ;
024: * libraryCall() ;
025: * ...
026: * } finally { model.leaveCriticalSection() ; }
027: *
028: * void libraryCall()
029: * {
030: * try {
031: * model.enterCriticalSection(ModelLock.READ) ;
032: * ... do library stuff ...
033: * } finally { model.leaveCriticalSection() ; }
034: * }
035: * </pre>
036: * Iterators should be used inside a critical section and not passed outside
037: * the concurrency controlled block.
038: * <pre>
039: * try {
040: * model.enterCriticalSection(ModelLock.READ) ;
041: * StmtIterator sIter = ... ;
042: * for ( ; sIter.next; )
043: * {
044: * ...
045: * }
046: * sIter.close() ;
047: * } finally { model.leaveCriticalSection() ; }
048: * </pre>
049: *
050: * Note that if a library operation needs a write lock, the application must either have no
051: * locks or a write lock when calling. Lock promotion is not supported - it can lead to
052: * deadlock.
053: *
054: * The hard work of locking is done by the
055: * <a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html">util.concurrent</a>.
056: * This is a convenience wrapper that provides nested locks, a special case of reentrant locks,
057: * that does some checking.
058: *
059: * @author Andy Seaborne
060: * @version $Id: Lock.java,v 1.4 2008/01/02 12:06:11 andy_seaborne Exp $
061: */package com.hp.hpl.jena.shared;
062:
063: public interface Lock {
064: /** Descriptive name for lock requests - read lock */
065: public static final boolean READ = true;
066:
067: /** Descriptive name for lock requests - write lock */
068: public static final boolean WRITE = false;
069:
070: /** Enter a critical section.
071: * The application must call leaveCriticialSection.
072: * @see #leaveCriticalSection
073: *
074: * @param readLockRequested true implies a read lock,false implies write lock.
075: */
076:
077: public void enterCriticalSection(boolean readLockRequested);
078:
079: /** Leave a critical section. Releases the lock form the matching enterCriticalSection
080: * @see #enterCriticalSection
081: */
082:
083: public void leaveCriticalSection();
084: }
085:
086: /*
087: * (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
088: * All rights reserved.
089: *
090: * Redistribution and use in source and binary forms, with or without
091: * modification, are permitted provided that the following conditions
092: * are met:
093: * 1. Redistributions of source code must retain the above copyright
094: * notice, this list of conditions and the following disclaimer.
095: * 2. Redistributions in binary form must reproduce the above copyright
096: * notice, this list of conditions and the following disclaimer in the
097: * documentation and/or other materials provided with the distribution.
098: * 3. The name of the author may not be used to endorse or promote products
099: * derived from this software without specific prior written permission.
100: *
101: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
102: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
103: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
104: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
105: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
106: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
107: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
108: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
109: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
110: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
111: */
|