org.apache.curator.framework.recipes.locks

Class InterProcessSemaphoreV2

java.lang.Object

org.apache.curator.framework.recipes.locks.InterProcessSemaphoreV2

public class InterProcessSemaphoreV2
extends Object

A counting semaphore that works across JVMs. All processes in all JVMs that use the same lock path will achieve an inter-process limited set of leases. Further, this semaphore is mostly "fair" - each user will get a lease in the order requested (from ZK's point of view).

There are two modes for determining the max leases for the semaphore. In the first mode the max leases is a convention maintained by the users of a given path. In the second mode a SharedCountReader is used as the method for semaphores of a given path to determine the max leases.

If a SharedCountReader is not used, no internal checks are done to prevent Process A acting as if there are 10 leases and Process B acting as if there are 20. Therefore, make sure that all instances in all processes use the same numberOfLeases value.

The various acquire methods return Lease objects that represent acquired leases. Clients must take care to close lease objects (ideally in a finally block) else the lease will be lost. However, if the client session drops (crash, etc.), any leases held by the client are automatically closed and made available to other clients.

Thanks to Ben Bangert (ben@groovie.org) for the algorithm used.

Constructor Summary

Constructors

Constructor and Description
InterProcessSemaphoreV2(org.apache.curator.framework.CuratorFramework client, String path, int maxLeases)
InterProcessSemaphoreV2(org.apache.curator.framework.CuratorFramework client, String path, SharedCountReader count)

Method Summary

Methods

Modifier and Type	Method and Description
Lease	acquire() Acquire a lease.
Collection<Lease>	acquire(int qty) Acquire qty leases.
Collection<Lease>	acquire(int qty, long time, TimeUnit unit) Acquire qty leases.
Lease	acquire(long time, TimeUnit unit) Acquire a lease.
Collection<String>	getParticipantNodes() Return a list of all current nodes participating in the semaphore
void	returnAll(Collection<Lease> leases) Convenience method.
void	returnLease(Lease lease) Convenience method.
void	setNodeData(byte[] nodeData) Set the data to put for the node created by this semaphore.

Methods inherited from class java.lang.Object

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

Constructor Detail

InterProcessSemaphoreV2

public InterProcessSemaphoreV2(org.apache.curator.framework.CuratorFramework client,
                       String path,
                       int maxLeases)

Parameters:

client - the client

path - path for the semaphore

maxLeases - the max number of leases to allow for this instance

InterProcessSemaphoreV2

public InterProcessSemaphoreV2(org.apache.curator.framework.CuratorFramework client,
                       String path,
                       SharedCountReader count)

Parameters:

client - the client

path - path for the semaphore

count - the shared count to use for the max leases

Method Detail

setNodeData

public void setNodeData(byte[] nodeData)

Set the data to put for the node created by this semaphore. This must be called prior to calling one of the acquire() methods.

Parameters:

nodeData - node data

getParticipantNodes

public Collection<String> getParticipantNodes()
                                       throws Exception

Return a list of all current nodes participating in the semaphore

Returns:

list of nodes

Throws:

Exception - ZK errors, interruptions, etc.

returnAll

public void returnAll(Collection<Lease> leases)

Convenience method. Closes all leases in the given collection of leases

Parameters:

leases - leases to close

returnLease

public void returnLease(Lease lease)

Convenience method. Closes the lease

Parameters:

lease - lease to close

acquire

public Lease acquire()
              throws Exception

Acquire a lease. If no leases are available, this method blocks until either the maximum number of leases is increased or another client/process closes a lease.

The client must close the lease when it is done with it. You should do this in a finally block.

Returns:

the new lease

Throws:

Exception - ZK errors, interruptions, etc.

acquire

public Collection<Lease> acquire(int qty)
                          throws Exception

Acquire qty leases. If there are not enough leases available, this method blocks until either the maximum number of leases is increased enough or other clients/processes close enough leases.

The client must close the leases when it is done with them. You should do this in a finally block. NOTE: You can use returnAll(Collection) for this.

Parameters:

qty - number of leases to acquire

Returns:

the new leases

Throws:

Exception - ZK errors, interruptions, etc.

acquire

public Lease acquire(long time,
            TimeUnit unit)
              throws Exception

Acquire a lease. If no leases are available, this method blocks until either the maximum number of leases is increased or another client/process closes a lease. However, this method will only block to a maximum of the time parameters given.

The client must close the lease when it is done with it. You should do this in a finally block.

Parameters:

time - time to wait

unit - time unit

Returns:

the new lease or null if time ran out

Throws:

Exception - ZK errors, interruptions, etc.

acquire

public Collection<Lease> acquire(int qty,
                        long time,
                        TimeUnit unit)
                          throws Exception

Acquire qty leases. If there are not enough leases available, this method blocks until either the maximum number of leases is increased enough or other clients/processes close enough leases. However, this method will only block to a maximum of the time parameters given. If time expires before all leases are acquired, the subset of acquired leases are automatically closed.

The client must close the leases when it is done with them. You should do this in a finally block. NOTE: You can use returnAll(Collection) for this.

Parameters:

qty - number of leases to acquire

time - time to wait

unit - time unit

Returns:

the new leases or null if time ran out

Throws:

Exception - ZK errors, interruptions, etc.