-
public interface ResourceContainer
AResourceContainer
defines a set of resourceConstraint
s that limit resource usage by threads. Zero or more threads can be attached to oneResourceContainer
.+-------------------------------+ +-----------------------------+ |ResourceContainer | |RootContainer | | | | | | +---------------+ | | | | |CPU Constraint | | | +----------+ | | +---------------+ <------------------+ Thread | | | +---------------+ | | +----------+ | | |Mem Constraint |command.run()| | container.run(command) | | +---------------+ | | | | | |----------------> v | | | | resources are command.run()| | | | controlled by returns | | back to root | | constraints +-----------------> container | | | | | | | | | +-------------------------------+ +-----------------------------+
The figure above describes the structure and usage ofResourceContainer
.The main Thread is bounded to root container which can be fetched by
root()
. Root Container is the system defaultResourceContainer
without any resource restrictions. Newly created threads are implicitly bounded toResourceContainer
of the parent thread.A Thread can invoke
run(Runnable command)
to attach to theResourceContainer
and run thecommand
, the resource usage of the thread is controlled by theResourceContainer
's constraints while running the command. When the execution of the command is either finished normally or terminated by Exception, the thread will be detached from the container automatically.Components of a
ResourceContainer
implementation:ResourceType
: an implementation can customize some ResourceTypeResourceContainer
: Implements a class extendsAbstractResourceContainer
ResourceContainerFactory
: service provider
ResourceContainer
needs to be created from a set ofConstraint
sIn most cases, the following idiom should be used:
ResourceContainer resourceContainer = containerFactory.createContainer( Arrays.asList( CPU_PERCENT.newConstraint(50), HEAP_RETAINED.newConstraint(100_000_000) )); resourceContainer.run(requestHandler); resourceContainer.destroy();
- See Also:
ResourceContainerFactory
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ResourceContainer.State
An enumeration of Container state
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description static ResourceContainer
current()
Returns the ResourceContainer associated with the current thread.void
destroy()
Destroys this resource container, also kills the attached threads and releases resources described ingetConstraints()
.Iterable<Constraint>
getConstraints()
Gets container'sConstraint
sLong
getConsumedAmount(ResourceType resourceType)
Long
getId()
ResourceContainer.State
getState()
Returns the current ResourceContainer state.static ResourceContainer
root()
Returns the system-wide "root" Resource container.void
run(Runnable command)
Attach the current thread to the ResourceContainer to run thecommand
, and detach the ResourceContainer whencommand
is either normally finished or terminated by Exception.void
updateConstraint(Constraint constraint)
UpdatesConstraint
of this resource container.
-
-
-
Method Detail
-
root
static ResourceContainer root()
Returns the system-wide "root" Resource container.Root ResourceContainer is a virtual container that indicates the default resource container for any thread, which is not attached to a ResourceContainer created by users. Root ResourceContainer does not have any resource constrains.
run(Runnable)
method of root container is a special implementation that detaches from the current container and returns to the root container. It is very useful in ResourceContainer switch scenario:// Assume we already attach to a non-root resourceContainer1 resourceContainer2.run(command); // throws exception, because it is illegal to switch between non-root // ResourceContainers ResourceContainer.root(() -> resourceContainer2.run(command));
- Returns:
- root container
-
current
static ResourceContainer current()
Returns the ResourceContainer associated with the current thread. For threads that do not attach to any user-created ResourceContainer,root()
is returned.- Returns:
- current ResourceContainer
-
getState
ResourceContainer.State getState()
Returns the current ResourceContainer state.- Returns:
- current state.
-
run
void run(Runnable command)
Attach the current thread to the ResourceContainer to run thecommand
, and detach the ResourceContainer whencommand
is either normally finished or terminated by Exception.At the same time, it is not allowed to switch directly between any two containers. If the switch is indeed required, the
root()
container should be used.This way restricts the container attach/detach mode for the API users, but is less error-prone.
ResourceContainer resourceContainer = .... assert ResourceContainer.current() == ResourceContainer.root(); resourceContainer.run(() -> { assert ResourceContainer.current() == resourceContainer; }); assert ResourceContainer.current() == ResourceContainer.root();
- Parameters:
command
- the target code
-
updateConstraint
void updateConstraint(Constraint constraint)
UpdatesConstraint
of this resource container.Constraints with an identical type will replace each other according to the calling order.
- Parameters:
constraint
- constraints list- Throws:
UnsupportedOperationException
-Constraint.getResourceType()
is not supported by the implementation
-
getConstraints
Iterable<Constraint> getConstraints()
Gets container'sConstraint
s- Returns:
Constraint
s
-
destroy
void destroy()
Destroys this resource container, also kills the attached threads and releases resources described ingetConstraints()
.Once this method is called, the state will become
ResourceContainer.State.STOPPING
. And the caller thread will be blocked until all the resources have been released. Then the container state will becomeResourceContainer.State.DEAD
.
-
getId
Long getId()
-
getConsumedAmount
Long getConsumedAmount(ResourceType resourceType)
-
-