net.jxta.impl.util
Interface ResourceAccount
- All Known Implementing Classes:
- ResourceDispatcher.ClientAccount
public interface ResourceAccount
A descriptor for a resource consumser. The resource consumer's resource
allocation and dynamic usage is tracked.
Method Summary |
void |
close()
Tear down this 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 this account needs a new item. |
boolean |
isIdle()
Tells if this account is idle (that is, none of the resources
that it controls are currently in use). |
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. |
close
void close()
- Tear down this account.
Releases all reserved resources.
obtainItem
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.
- Returns:
- boolean true if an item was granted, false otherwise.
obtainQuantity
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.
- 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.
releaseItem
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.
- Returns:
- ResourceAccount the account to which the released item
has been re-assigned. null if the released item was not re-assigned.
releaseQuantity
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.
- Parameters:
quantity
- the number of items to be released.
inNeed
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.
- Parameters:
needs
- Whether the account needs a new item or not.
getUserObject
Object getUserObject()
- Returns:
- Object The userObject that was supplied when creating the
account.
setUserObject
void setUserObject(Object obj)
- Set the userObject associated with that account.
getNbReserved
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.
- Returns:
- long The number of reserved items.
isIdle
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.