net.jxta.impl.util
Class ResourceDispatcher.ClientAccount

java.lang.Object
  net.jxta.impl.util.Dlink
      net.jxta.impl.util.ResourceDispatcher.ClientAccount

All Implemented Interfaces:

ResourceAccount

Enclosing class:

ResourceDispatcher

 class ResourceDispatcher.ClientAccount
extends Dlink
implements ResourceAccount

ResourceDispatcher.ClientAccount

ResourceDispatcher.ClientAccount(long fromReservedItems,
                                 long fromExtraItems,
                                 long extraLimit,
                                 Object userObject)

Creates a client account with this resource manager. Not for external use.

Parameters:

fromReservedItems -

fromExtraItems -

extraLimit -

userObject -

close

public void close()

Tear down this account. Releases all reserved resources.

To accelerate return of resources to the global pool, one may call close() explicitly. Otherwise it is called by finalize.

Calling close() or letting the account be GC'ed while some of the resources have not been returned is an error, may create a leak and may display a warning message.

Specified by:

close in interface ResourceAccount

finalize

protected void finalize()
                 throws Throwable

Will close the account. (close is idempotent).

Overrides:

finalize in class Object

Throws:

Throwable

isIdle

public boolean isIdle()

Tells if this account is idle (that is, none of the resources that it controls are currently in use). This means it can be closed safely.

Specified by:

isIdle in interface ResourceAccount

isEligible

public boolean isEligible()

beEligible

public void beEligible()

Put that account in the queue of accounts eligible to receive a resource when one becomes available.

notEligible

public void notEligible()

Remove that account from the queue of accounts eligible to receive a resource when one becomes available.

obtainQuantity

public boolean obtainQuantity(long quantity)

Try and grant a certain quantity.

It is useful to manage the allocation of variable sized aggregates when what matters is the cummulated quantity rather than an item count. Quantity could be a number of bytes needed to store something for example. The advantage of using this method rather than obtainItem repeatedly is that it is obvisouly faster if quantity is more than one or two, and also that it is atomic; the entire quantity is either granted or denied. Using this routine is by definition incompatible with the round-robin mode, which could only re-assign quantities of 1.

It is legal to use this routine along with round-robin mode if the same dispatcher is used to manage quantities of 1 in this manner, but an account that has failed to obtain its desired quantity is not queued for later re-assignment. And items released with releaseQuantity() are not re-assigned, so overall it is probably best to not mix the two.

Specified by:

obtainQuantity in interface ResourceAccount

Parameters:

quantity - The number of units wanted. The unit is arbitrary It is only meaningfull to the code that uses this dispatcher.

Returns:

boolean whether the requested quantity is authorized.

obtainItem

public boolean obtainItem()

Try and grant a new item to this account. If it cannot be done, the account may be eligible for the next available extra item. The account is automatically set to be in need, as if inNeed(true) has been invoked.

Specified by:

obtainItem in interface ResourceAccount

Returns:

boolean true if an item was granted, false otherwise.

releaseQuantity

public void releaseQuantity(long quantity)

This will release a number of items at once rather than once. To be used in conjunctino with obtainItems(). See that method.

Specified by:

releaseQuantity in interface ResourceAccount

Parameters:

quantity - the number of items to be released.

releaseItem

public ResourceAccount releaseItem()

This will release an item and return the most eligible account to re-use this item for. The account that is returned has been granted the item and thus the invoker is expected to do with this account whatever an invoker of obtainItem() would do in case of success. If the items that are managed are threads, the invoker is likely to be one these threads and it should therefore process the returned account as it did the one for which it was calling releaseItem, however be very carefull not to process the new account in the context of the old one; that would rapidly lead to stack overflow. In other words, be carefull of not making a construct equivalent to:

 process() {
   doStuff();
   myAccount.releaseItem().getUserObject().process();
 }
 

That won't work. Instead do:

 work() {
  while (myAccount != null) {
   myAccount.getUserObject().doStuff();
   myAccount = myAccount.releaseItem();
  }
 }
 

Or similar; always go back to base stack level. It is mandatory to handle accounts returned by releaseItem(). If handling leads to releaseItem, then it has to be done in a forever loop. That is typical if the items are threads. That is normally not happening if the items are only memory.

Specified by:

releaseItem in interface ResourceAccount

Returns:

ResourceAccount the account to which the released item has been re-assigned. null if the released item was not re-assigned.

inNeed

public void inNeed(boolean needs)

Call this with true as soon as this account needs a new item. Call this with false as soon as this account has all that it needs. For proper operation, this must be done.

Specified by:

inNeed in interface ResourceAccount

Parameters:

needs - Whether the account needs a new item or not.

getUserObject

public Object getUserObject()

Specified by:

getUserObject in interface ResourceAccount

Returns:

Object The userObject that was supplied when creating the account.

setUserObject

public void setUserObject(Object object)

Set the userObject associated with that account.

Specified by:

setUserObject in interface ResourceAccount

getNbReserved

public long getNbReserved()

Returns the number of reserved items that can still be obtained by this account.

If that number is negative or zero, it means that all reserved items are currently in use. Still more items might still be obtained from the extra items pool.

Specified by:

getNbReserved in interface ResourceAccount

Returns:

long The number of reserved items.

toString

public String toString()

Returns some human-readable status and identity information useful for debugging.

Overrides:

toString in class Object