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
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. |
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 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.