.. index:: double: throttling; plugins double: throttle; plugins Throttling policies =================== .. _run-programs-plugin-throttle: The throttle policy determines when tasks are created as entities, that can be scheduled and executed asynchronously, or are executed immediately, as if the code were not meant to be executed in parallel. Applications may be sensitive to this behavior so different throttling policies are provided by Nanos++ in order to allow a more precise tuning of the system. Usage ----- | *Description:* Sets the throttling policy that will be used during the execution. | *Type:* string value. | *Environment variable*: ``NX_THROTTLE=`` | *Command line flag:* ``--throttle[ |=]`` List of throttling plugins -------------------------- Throttle policies are provided in the form of plug-ins. Currently Nanos++ comes with the following throttling policies: .. index:: double: throttling; histeresys double: throttle; histeresys Hysteresis ^^^^^^^^^^ .. important:: This is the default throttling policy * *Configuration string:* ``NX_THROTTLE=hysteresis`` *or* ``NX_ARGS="--throttle=hysteresis"`` * *Description:* Based on the hysteresis mechanisms, once we reach to a upper limit we stop creating tasks but we start to create them again when we reach a lower limit. Upper limit and lower limit are configurable through command line flags: * *Parameters:* --throttle-upper Defines the maximum number of tasks per thread allowed to create new first level's tasks. (default value 500). --throttle-lower Defines the number of tasks per thread to re-active first level task creation. (default value 250). --throttle-type Defines the target counter when taking into account the number of tasks. User can choose among ``ready`` or ``total``. (default value total). .. index:: double: throttling; task depth double: throttle; task depth Task depth ^^^^^^^^^^ * *Configuration string:* ``NX_THROTTLE=taskdepth`` *or* ``NX_ARGS=--throttle=taskdepth"`` * *Description:* This throttle mechanism is based on the task depth. The runtime will not create tasks further than the nested level specified by the limit. * *Parameters:* --throttle-limit Defines maximum depth for tasks. (default value 4). .. index:: double: throttling; ready tasks double: throttle; ready tasks Ready tasks ^^^^^^^^^^^ * *Configuration string:* ``NX_THROTTLE=readytasks`` *or* ``NX_ARGS="--throttle=readytasks"`` * *Description:* Defines the throttle policy according with the number of ready tasks while creating a new task. * *Parameters:* --throttle-limit Defines the number of ready tasks we use as limit for task creation. When creating a task, if the number of ready tasks is greater than limit task will not be created, task creation will block and issued to scheduler decision. If number of ready tasks is less or equal than limit, task will be created normally. (default value 100). .. index:: double: throttling; idle threads double: throttle; idle threads Idle threads ^^^^^^^^^^^^ * *Configuration string:* ``NX_THROTTLE=idlethreads`` *or* ``NX_ARGS="--throttle=idlethreads`` * *Description:* This throttle policy take the decision of create (or not) a task according with the number of idle threads we have at task creation instant. * *Parameters:* --throttle-limit Defines the number of idle threads we use as limit for task creation. When creating a task, if the number of idle threads is less than this value the task will not be created, task creation will block and issued to scheduler decision. If number of idle threads is greater or equal than this limit, the task will be created normally. (default value is 0). .. index:: double: throttling; number of tasks double: throttle; number of tasks Number of tasks ^^^^^^^^^^^^^^^ * *Configuration string:* ``NX_THROTTLE=numtasks`` *or* ``NX_ARGS=--thottle=numtasks`` * *Description:* Defines the throttle policy according with the existing number of tasks at task creation. * *Parameters:* --throttle-limit Defines the number of tasks (total tasks already created and not completed, being ready or not) we use as limit for task creation. When creating a task, if the number of on-fly-tasks is greater than limit the task will not be created, task creation will be blocked and issued to scheduler decision. If number of on-fly-tasks is less or equal than this limit, the task will be created normally. (default value 100). .. index:: double: throttling; dummy double: throttle; dummy Dummy ^^^^^ * *Configuration string:* ``NX_THROTTLE=dummy`` *or* ``NX_ARGS="--throttle=dummy"`` * *Description:* This throttle policy always takes the decision of create (or not) tasks. * *Parameters:* --throttle-create-tasks Set the behaviour of the dummy throttle to force task creation and deferred execution. (default option). --no-throttle-create-tasks Set the behaviour of the dummy throttle to avoid task creation and force undeferred execution. .. index:: double: throttling; examples double: throttle; examples Throttle policy examples ------------------------ If we want to execute our program with 4 threads and using a throttling policy which create tasks only if we have at least one thread idle, we will use the following command line:: NX_ARGS="--threads=4 --throttle=idlethreads --throttle-limit=1" ./myProgram If we want to execute our program with 8 threads and using a throttling policy which create tasks only if we do not have at least 50 ready tasks per thread, we will use the following command line:: NX_ARGS="--threads=8 --throttle=readytasks --throttle-limit=50" ./myProgram