gnu.iou
Class lck

java.lang.Object
  |
  +--gnu.iou.lck

public class lck

extends java.lang.Object

Particular type of locker ("mutex") serializes entry into area(s) "protected" by a `lck.serialize()' "gate" or "gateway".

The "serialize" function allows one thread past at a time. Each thread past "serialize" MUST call "unlock" once it's done in the locked area, in order to exit the locked area and to allow the next thread in.

If one lock object has its "serialize" gateway used in multiple places, then all of those areas will be serialized -- one thread enters their collective whole area at a time.

A thread can reenter the serialized area.

Usage

 lck locker = new lck();

 ...

 try {
     locker.serialize();
     
     return somefun();
 }
 finally {
     locker.unlock();
 }
 

Author:

John Pritchard (john@syntelos.org)

Field Summary

static boolean	debug
static boolean	debug_trace

Constructor Summary

lck()
New locker constructor

lck(boolean reenterable)
Define the reentry character of this mutex.

Method Summary

int	entered() Number of threads entered past this lock.
boolean	isLocked() If a thread has entered `serialized', the lock is considered "locked".
static java.lang.String	LckDesc(java.lang.Object user, lck lock) Use the `lck' user- object to lookup a user lock descriptor string.
static void	LckDesc(java.lang.Object user, java.lang.String desc) Use the `lck' user object to setup a user lock descriptor string.
static java.lang.String	LckDescRm(java.lang.Object user) Use the `lck' user- object to delete a user lock descriptor string from cache.
void	serialize(java.lang.Object user) The "lck" gate function.
java.lang.String	toString() Classname with "entered" parameter in usual "java" square bracket format.
void	unlock(java.lang.Object user) The "lck" gate keeper function.
int	waiters() Number of threads waiting on this lock (waiting behind the gate).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

debug

public static boolean debug

debug_trace

public static boolean debug_trace

Constructor Detail

lck

public lck()

New locker constructor

lck

public lck(boolean reenterable)

Define the reentry character of this mutex.

Parameters:

reenterable - If true, allow thread reentry as default. If false, throw a runtime exception on reentry.

Method Detail

LckDesc

public static final void LckDesc(java.lang.Object user,
                                 java.lang.String desc)

Use the `lck' user object to setup a user lock descriptor string.

This does not keep a reference to the user object, preventing it from being garbage collected (and finalized).

Call "LckDescRm" from the user- object's "finalize" method.

See Also:

LckDescRm(java.lang.Object)

LckDesc

public static final java.lang.String LckDesc(java.lang.Object user,
                                             lck lock)

Use the `lck' user- object to lookup a user lock descriptor string.

LckDescRm

public static final java.lang.String LckDescRm(java.lang.Object user)

Use the `lck' user- object to delete a user lock descriptor string from cache. (Can call this from the user's "finalize".)

serialize

public final void serialize(java.lang.Object user)

The "lck" gate function. Each method calls this typically on entering a "lck"- protected area. Only one thread is allowed past at a time.

Parameters:

user - The object maintaining and using the lock. The object that has a field for the lock (see "LckDesc").

See Also:

LckDesc(java.lang.Object, java.lang.String)

unlock

public final void unlock(java.lang.Object user)

The "lck" gate keeper function. Each thread exiting the "lck"- protected area calls on this unlock function to allow the next thread to enter the protected ("serialized") area.

Parameters:

user - The object maintaining and using the lock. The object that has a field for the lock (see "LckDesc").

See Also:

LckDesc(java.lang.Object, java.lang.String)

isLocked

public final boolean isLocked()

If a thread has entered `serialized', the lock is considered "locked".

entered

public final int entered()

Number of threads entered past this lock. Should be zero or one!

waiters

public final int waiters()

Number of threads waiting on this lock (waiting behind the gate).

toString

public java.lang.String toString()

Classname with "entered" parameter in usual "java" square bracket format.

Overrides:

toString in class java.lang.Object