Project JXTA

net.jxta.impl.util
Class ResourceDispatcher.ClientAccount

java.lang.Object
  extended bynet.jxta.impl.util.Dlink
      extended bynet.jxta.impl.util.ResourceDispatcher.ClientAccount
All Implemented Interfaces:
ResourceAccount
Enclosing class:
ResourceDispatcher

class ResourceDispatcher.ClientAccount
extends Dlink
implements ResourceAccount


Constructor Summary
(package private) ResourceDispatcher.ClientAccount(long fromReservedItems, long fromExtraItems, long extraLimit, Object userObject)
          Creates a client account with this resource manager.
 
Method Summary
 void beEligible()
          Put that account in the queue of accounts elligible to receive a resource when one becomes available.
 void close()
          Tear down this client account.
 void finalize()
          Will close the account.
 long getNbReserved()
          Returns the number of reserved items that can still be obtained by this account.
 Object getUserObject()
           
 void inNeed(boolean needs)
          Call this with true as soon as account needs a new item.
 boolean isEligible()
           
 boolean isIdle()
          Tells if this account is idle (that is, none of the resources that it controls are currently in use).
 void notEligible()
          Remove that account from the queue of accounts elligible to receive a resource when one becomes available.
 boolean obtainItem()
          Try and grant a new item to this account.
 boolean obtainQuantity(long quantity)
          Try and grant a certain quantity.
 ResourceAccount releaseItem()
          This will release an item and return the most eligible account to re-use this item for.
 void releaseQuantity(long quantity)
          This will release a number of items at once rather than once.
 void setUserObject(Object obj)
          Set the userObject associated with that account.
 String toString()
          Returns some human-readable status and identity information.
 
Methods inherited from class net.jxta.impl.util.Dlink
isLinked, linkNewNext, linkNewPrev, next, prev, unlink
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

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 -
Method Detail

close

public void close()
Tear down this client account. Return reserved resources to the main pool. 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

public void finalize()
Will close the account. (close is idempotent).


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 elligible to receive a resource when one becomes available.


notEligible

public void notEligible()
Remove that account from the queue of accounts elligible to receive a resource when one becomes available.


obtainQuantity

public boolean obtainQuantity(long quantity)
Try and grant a certain quantity. It is usefull 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. That there is need is assumed (otherwise, why is this called ?).

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. No choice. That's typical if the items are threads. That's normally not happening if the items are memory. If this account is not using any extra item, it is the only eligible account to reuse this item. In that case, if this account needs the item, "this" is returned. Else the item is accounted as released and null is returned. If this account is using extra items, the item is accounted as released for this account, and granted to the most eligible account, which is returned. If roundRobin mode is OFF, the most eligible account can only be this. If no account has any need for the item, the item is counted as released for this item and globaly, and null is returned. If RoundRobin is ON, this account may not always be eligible for an extra item.

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 account needs a new item. Call this with false as soon as account has all it needs. Accounts are taken out of the eligible list as soon as one item is obtained. Calling inNeed() is a way to get the item back in list (at the end) if the need is still present.

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 obj)
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 it means that all reserved items are currently in use, and the number is the opposite of the number of extra items that are also currently in use by that account.

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.


JXTA J2SE