Github user rfarivar commented on a diff in the pull request:
https://github.com/apache/storm/pull/921#discussion_r47668082
--- Diff: docs/documentation/Resource_Aware_Scheduler_overview.md ---
@@ -0,0 +1,224 @@
+# Introduction
+
+The purpose of this document is to provide a description of the Resource
Aware Scheduler for the Storm distributed real-time computation system. This
document will provide you with both a high level description of the resource
aware scheduler in Storm
+
+## Using Resource Aware Scheduler
+
+The user can switch to using the Resource Aware Scheduler by setting the
following in *conf/storm.yaml*
+
+ storm.scheduler:
âbacktype.storm.scheduler.resource.ResourceAwareSchedulerâ
+
+
+## API Overview
+
+For a Storm Topology, the user can now specify the amount of resources a
topology component (i.e. Spout or Bolt) is required to run a single instance of
the component. The user can specify the resource requirement for a topology
component by using the following API calls.
+
+### Setting Memory Requirement
+
+API to set component memory requirement:
+
+ public T setMemoryLoad(Number onHeap, Number offHeap)
+
+Parameters:
+* Number onHeap â The amount of on heap memory an instance of this
component will consume in megabytes
+* Number offHeap â The amount of off heap memory an instance of this
component will consume in megabytes
+
+The user also has to option to just specify the on heap memory requirement
if the component does not have an off heap memory need.
+
+ public T setMemoryLoad(Number onHeap)
+
+Parameters:
+* Number onHeap â The amount of on heap memory an instance of this
component will consume
+
+If no value is provided for offHeap, 0.0 will be used. If no value is
provided for onHeap, or if the API is never called for a component, the default
value will be used.
+
+Example of Usage:
+
+ SpoutDeclarer s1 = builder.setSpout("word", new TestWordSpout(), 10);
+ s1.setMemoryLoad(1024.0, 512.0);
+ builder.setBolt("exclaim1", new ExclamationBolt(), 3)
+ .shuffleGrouping("word").setMemoryLoad(512.0);
+
+The entire memory requested for this topology is 16.5 GB. That is from 10
spouts with 1GB on heap memory and 0.5 GB off heap memory each and 3 bolts with
0.5 GB on heap memory each.
+
+### Setting CPU Requirement
+
+
+API to set component CPU requirement:
+
+ public T setCPULoad(Double amount)
+
+Parameters:
+* Number amount â The amount of on CPU an instance of this component
will consume.
+
+Currently, the amount of CPU resources a component requires or is
available on a node is represented by a point system. CPU usage is a difficult
concept to define. Different CPU architectures perform differently depending on
the task at hand. They are so complex that expressing all of that in a single
precise portable number is impossible. Instead we take a convention over
configuration approach and are primarily concerned with rough level of CPU
usage while still providing the possibility to specify amounts more fine
grained.
+
+By convention a CPU core typically will get 100 points. If you feel that
your processors are more or less powerful you can adjust this accordingly.
Heavy tasks that are CPU bound will get 100 points, as they can consume an
entire core. Medium tasks should get 50, light tasks 25, and tiny tasks 10. In
some cases you have a task that spawns other threads to help with processing.
These tasks may need to go above 100 points to express the amount of CPU they
are using. If these conventions are followed the common case for a single
threaded task the reported Capacity * 100 should be the number of CPU points
that the task needs.
+
+Example of Usage:
--- End diff --
Suggest adding another bolt to this example and setting its CPU usage to a
number higher than 100, e.g. 450.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
