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.
| Modifier and Type | Field and Description |
|---|---|
static Set<String> |
LOCK_SCHEMA |
| Constructor and Description |
|---|
InterProcessSemaphoreV2(CuratorFramework client,
String path,
int maxLeases) |
InterProcessSemaphoreV2(CuratorFramework client,
String path,
SharedCountReader count) |
| 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.
|
public InterProcessSemaphoreV2(CuratorFramework client, String path, int maxLeases)
client - the clientpath - path for the semaphoremaxLeases - the max number of leases to allow for this instancepublic InterProcessSemaphoreV2(CuratorFramework client, String path, SharedCountReader count)
client - the clientpath - path for the semaphorecount - the shared count to use for the max leasespublic void setNodeData(byte[] nodeData)
nodeData - node datapublic Collection<String> getParticipantNodes() throws Exception
Exception - ZK errors, interruptions, etc.public void returnAll(Collection<Lease> leases)
leases - leases to closepublic void returnLease(Lease lease)
lease - lease to closepublic 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.
Exception - ZK errors, interruptions, etc.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.
qty - number of leases to acquireException - ZK errors, interruptions, etc.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.
time - time to waitunit - time unitException - ZK errors, interruptions, etc.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.
qty - number of leases to acquiretime - time to waitunit - time unitException - ZK errors, interruptions, etc.Copyright © 2011–2023 The Apache Software Foundation. All rights reserved.