com.gemstone.gemfire.distributed
Class DistributedLockService

A named instance of DistributedLockService defines a space for
locking arbitrary names across the distributed system defined by
a specified distribution manager. Any number of DistributedLockService
instances can be created with different service names. For all
processes in the distributed system that have created an instance of
DistributedLockService with the same name, no more than one thread
is permitted to own the lock on a given name in that instance at any
point in time. Additionally, a thread can lock the entire service,
preventing any other threads in the system from locking the service
or any names in the service.

Method Summary

abstract void

becomeLockGrantor()
Specifies this member to become the grantor for this lock service.

static void

becomeLockGrantor(String serviceName)
Specifies that this member should become the grantor for the named locking
service.

create

Create a DistributedLockService with the given serviceName for the
given DistributedSystem. This DistributedLockService will
continue to manage locks until destroy(java.lang.String)
is called, or ds is disconnected, at which point any
locks that were held by this instance are released.

Parameters:

serviceName - the name of the DistributedLockService to create.

ds - the DistributedSystem for the new service instance
to use for distributed lock messaging.

Throws:

IllegalArgumentException - if serviceName is an illegal name or
this process has already created a DistributedLockService with the given
serviceName.

destroy

Destroy a previously created DistributedLockService with the given
serviceName. Any locks currently held in this
DistributedLockService by this process are released. Attempts to
access a destroyed lock service will result in a LockServiceDestroyedException being thrown.

Parameters:

serviceName - the name of the instance to destroy, previously
supplied in the create(String, DistributedSystem)
invocation.

lock

public abstract boolean lock(Object name,
long waitTimeMillis,
long leaseTimeMillis)

Attempts to acquire a lock named name. Returns
true as soon as the lock is acquired. If the lock
is currently held by another thread in this or any other process
in the distributed system, or another thread in the system has locked
the entire service, this method keeps trying to acquire the lock for
up to waitTimeMillis before giving up and returning
false. If the lock is acquired, it is held until
unlock(Object name) is invoked, or until
leaseTimeMillis milliseconds have passed since the
lock was granted - whichever comes first.

Locks are reentrant. If a thread invokes this method n times
on the same instance, specifying the same name, without
an intervening release or lease expiration expiration on the lock,
the thread must invoke unlock(name) the same number of
times before the lock is released (unless the lease expires). When
this method is invoked for a lock that is already acquired, the
lease time will be set to the maximum of the remaining least time
from the previous invocation, or leaseTimeMillis

Parameters:

name - the name of the lock to acquire in this service. This object
must conform to the general contract of equals(Object) and
hashCode() as described in
Object.hashCode().

waitTimeMillis - the number of milliseconds to try to acquire
the lock before giving up and returning false. A value of -1 causes
this method to block until the lock is acquired. A value of 0 causes
this method to return false without waiting for the lock if the lock is
held by another member or thread.

leaseTimeMillis - the number of milliseconds to hold the lock after
granting it, before automatically releasing it if it hasn't already
been released by invoking unlock(Object). If
leaseTimeMillis is -1, hold the lock until explicitly
unlocked.

Returns:

true if the lock was acquired, false if the timeout
waitTimeMillis passed without acquiring the lock.

Attempts to acquire a lock named name. Returns
true as soon as the lock is acquired. If the lock
is currently held by another thread in this or any other process
in the distributed system, or another thread in the system has locked
the entire service, this method keeps trying to acquire the lock for
up to waitTimeMillis before giving up and returning
false. If the lock is acquired, it is held until
unlock(Object name) is invoked, or until
leaseTimeMillis milliseconds have passed since the
lock was granted - whichever comes first.

Locks are reentrant. If a thread invokes this method n times
on the same instance, specifying the same name, without
an intervening release or lease expiration expiration on the lock,
the thread must invoke unlock(name) the same number of
times before the lock is released (unless the lease expires). When
this method is invoked for a lock that is already acquired, the
lease time will be set to the maximum of the remaining least time
from the previous invocation, or leaseTimeMillis

Parameters:

name - the name of the lock to acquire in this service. This object
must conform to the general contract of equals(Object) and
hashCode() as described in
Object.hashCode().

waitTimeMillis - the number of milliseconds to try to acquire
the lock before giving up and returning false. A value of -1 causes
this method to block until the lock is acquired.

leaseTimeMillis - the number of milliseconds to hold the lock after
granting it, before automatically releasing it if it hasn't already
been released by invoking unlock(Object). If
leaseTimeMillis is -1, hold the lock until explicitly
unlocked.

Returns:

true if the lock was acquired, false if the timeout
waitTimeMillis passed without acquiring the lock.

suspendLockingInterruptibly

Suspend granting of locks in this service. When locking has been
suspended, no other thread in the distributed system will be granted a lock
for any new or existing name in that service until locking is resumed by
the thread that suspended it. Only one thread at a time in a distributed
system is permitted suspend locking on a given DistributedLockService
instance. This method blocks until lock suspension can be granted to the
current thread, and all outstanding locks on names in this service held by
other threads in the distributed system have been released, or until
waitTimeMillis milliseconds have passed without successfully
granting suspension.

Parameters:

waitTimeMillis - the number of milliseconds to try to acquire
suspension before giving up and returning false. A value
of -1 causes this method to block until suspension is granted.

Returns:

true if suspension was granted, false if the
timeout waitTimeMillis passed before it could
be granted.

suspendLocking

public abstract boolean suspendLocking(long waitTimeMillis)

Suspend granting of locks in this service. When locking has been
suspended, no other thread in the distributed system will be granted a lock
for any new or existing name in that service until locking is resumed by
the thread that suspended it. Only one thread at a time in a distributed
system is permitted suspend locking on a given DistributedLockService
instance. This method blocks until lock suspension can be granted to the
current thread, and all outstanding locks on names in this service held by
other threads in the distributed system have been released, or until
waitTimeMillis milliseconds have passed without successfully
granting suspension.

Parameters:

waitTimeMillis - the number of milliseconds to try to acquire
suspension before giving up and returning false. A value of -1 causes
this method to block until suspension is granted. A value of 0 causes
this method to return false without waiting for the lock if the lock is
held by another member or thread.

Returns:

true if suspension was granted, false if the
timeout waitTimeMillis passed before it could
be granted.

becomeLockGrantor

public abstract void becomeLockGrantor()

Specifies this member to become the grantor for this lock service. The
grantor will be the lock authority which is responsible for handling all
lock requests for this service. Other members will request locks from
this member. Locking for this member is optimized as it will not require
messaging to acquire a given lock.

Calls to this method will block until grantor authority has been
transferred to this member.

If another member calls becomeLockGrantor after this member,
that member will transfer grantor authority from this member to itself.

This operation should not be invoked repeatedly in an application. It is
possible to create a lock service and have two or more members endlessly
calling becomeLockGrantor to transfer grantorship back and forth.

isLockGrantor

public abstract boolean isLockGrantor()

Returns true if this member is currently the lock authority responsible
for granting locks for this service. This can be explicitly requested by
calling becomeLockGrantor().
If no member has explicitly requested grantor authority, then one member
participating in the service will be implicitly selected. In either case,
this method returns true if the calling member is the grantor.