Module java.base

Interface ResourceContainer


  • public interface ResourceContainer
    A ResourceContainer defines a set of resource Constraints that limit resource usage by threads. Zero or more threads can be attached to one ResourceContainer.
     +-------------------------------+  +-----------------------------+
     |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 of ResourceContainer.

    The main Thread is bounded to root container which can be fetched by root(). Root Container is the system default ResourceContainer without any resource restrictions. Newly created threads are implicitly bounded to ResourceContainer of the parent thread.

    A Thread can invoke run(Runnable command) to attach to the ResourceContainer and run the command, the resource usage of the thread is controlled by the ResourceContainer'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 ResourceType
    • ResourceContainer: Implements a class extends AbstractResourceContainer
    • ResourceContainerFactory: service provider

    ResourceContainer needs to be created from a set of Constraints

    In 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
    • 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 the command, and detach the ResourceContainer when command 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
      • getId

        Long getId()