org.rhq.enterprise.communications.util

Class ConcurrencyManager

java.lang.Object

org.rhq.enterprise.communications.util.ConcurrencyManager

public class ConcurrencyManager
extends Object

This is basically a thread gatekeeper that allows a thread to ask for permission to continue.

Under the covers, this object uses a set of named counting semaphores. A calling thread asks for permission by giving a name to getPermit(String); if no more permits are available on the named semaphore, this manager will throw a runtime exception. In effect, it will abort a thread unless that thread is permitted to continue. Because this manager maintains a dynamic set of named counting semaphores, you can have groups of threads that are allowed to operate independently of other groups of threads (i.e. each group of threads can use their own named semaphore).

Each counting semaphore will be given a default number of total permits. You can set a custom number of permits per counting semaphore by passing in a set of names with their associated number-of-permits-allowed to the constructor.

Author:

John Mazzitelli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConcurrencyManager.Permit

Constructor Summary

Constructors

Constructor and Description
ConcurrencyManager(Map<String,Integer> newPermitsAllowed)

Method Summary

Methods

Modifier and Type	Method and Description
Map<String,Integer>	getAllConfiguredNumberOfPermitsAllowed() Returns a copy of the map with all named permits and how many are allowed to be concurrently held.
int	getConfiguredNumberOfPermitsAllowed(String name) If the named semaphore has a configured number-of-permits-allowed (numPermitsAllowed) then the number of permits allowed is returned.
ConcurrencyManager.Permit	getPermit(String name) Asks to obtain a permit to continue.
void	releasePermit(ConcurrencyManager.Permit permit) Returns the permission that was previously granted to the caller.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConcurrencyManager

public ConcurrencyManager(Map<String,Integer> newPermitsAllowed)

Method Detail

getPermit

public ConcurrencyManager.Permit getPermit(String name)
                                    throws NotPermittedException

Asks to obtain a permit to continue. The given name is that of the semaphore whose permit the caller will attempt to acquire. If name is null, this method will return always (in effect, the null semaphore allows an unlimited number of permits).

Parameters:

name - the name of the semaphore to acquire the permit from (note: this has nothing to do with the name of a thread or thread group) (may be null)

Returns:

the permit that allows the thread to continue. The caller must eventually release it.

Throws:

NotPermittedException - if the calling thread cannot obtain a permit

releasePermit

public void releasePermit(ConcurrencyManager.Permit permit)

Returns the permission that was previously granted to the caller.

Parameters:

permit - the permit that was previously granted that is now being released (may be null)

getAllConfiguredNumberOfPermitsAllowed

public Map<String,Integer> getAllConfiguredNumberOfPermitsAllowed()

Returns a copy of the map with all named permits and how many are allowed to be concurrently held. The returned map is a copy and not backed by this manager. Note that this returns the map of explicitly declared or determined permits allowed, it will not return information on concurrency limits that may have defaults defined in system properties but has not actually been used yet by this concurrency manager.

Returns:

map keyed on permit names whose values are the number of times the permit can be concurrently held

getConfiguredNumberOfPermitsAllowed

public int getConfiguredNumberOfPermitsAllowed(String name)

If the named semaphore has a configured number-of-permits-allowed (numPermitsAllowed) then the number of permits allowed is returned. Otherwise, this checks system properties - if there is a system property with the given name, the value of the system property is returned. Its possible this method will return a value for name where that name in the map returned by getAllConfiguredNumberOfPermitsAllowed() has no value - this is due to the fact that this method checks system properties as a fall back.

Parameters:

name - the name of the semaphore

Returns:

number of permits allowed on the named semaphore