Automatic Interception Interface Usage

Automatic Interception Interface Usage

Overview

The general procedure for implementing Automatic Interception Interface for your application is as follows:

  1. Make sure the tool managing the process to be distributed supports parallel execution of non-dependent processes.
  2. Create a Profile XML file describing the tools which are to be executed remotely and also describes the tools that are invokers.
  3. Create a Profile XML file that specifies the settings for each task that you want IncrediBuild to handle, whether they are tasks that are invokers or tasks that you want to run remotely. Tasks that you do not want IncrediBuild to handle, you do not have to declare in the XML profile file.

    For each invoker task, set
    AllowIntercept=true

    The main executable in your software should be defined in the profile XML with the AllowIntercept attribute set to "True".

    If the process to be executed remotely is spawned by a child process of the main executable, the entire hierarchy of processes starting from the main executable should have the AllowIntercept attribute set to "True".

    For example, if the main project is "a", which executes "b", and "b" executes "c" (the process whose execution we wish to distribute), then both "a" and "b" must be specified with the AllowIntercept attribute set to "True".

    For each task that is to be distributed to a remote machine, set
    AllowRemote=true
  4. Run the application or tool to be accelerated with IncrediBuild, through the IBConsole command, supplying the name of the profile XML file and either a command line for the Job, or the name of the batch file containing the command that executes your application (see below for more details). For testing purposes, run the application in such a way that it will activate more processes than the number of cores that you have on the local machine so that IncrediBuild will have to do distribution for some of the processes on a remote machine.
    If you are running IBConsole.exe with the "/COMMAND=" syntax, the application specified in the /COMMAND argument (or cmd.exe for a .bat file) will be implicitly given the AllowIntercept behavior.

Note:

Using IBConsole.exe with the Automatic Interception Interface

Once the above steps have been performed, a command line string can be used to run any tool with parallel process execution mode.
This command line should be specified as an input argument to IBConsole.exe (see examples below).
Note that the profile XML file is also specified in the command line arguments.

The process should execute in local parallel mode, with tools specified with "AllowRemote=True" in the Profile XML file executed on remote machines.

The basic command line syntax for running a distributed XML job through the XML Interface is:

IBConsole.exe /command="<TOOL COMMAND>" /profile="<PROFILE XML>" [Other Options]

Where:

Where:

Example

Let us say you have an application called RenderApp.exe, which knows to run in parallel many tasks of RenderTask.exe, where each RenderTask.exe gets a frame and renders it. If you run this application in a regular way, i.e. without multiple cores, you can call it as follows:

RenderApp 1-1000

This causes the application to run sequentially 1000 tasks of RenderTask.exe, and each time to bring it a frame (from 1-1000) and render it. Doing so means that it will take 1000 times the time needed to process one frame, to complete the rendering of all the frames.

Instead of using this method, you can use another method, also supported by this application. In this method, the local cores on the local machine are used. In this case, you call RenderApp to run on four cores, as follows:

RenderApp 1-1000 –cores4

This causes the application to run four RenderTask.exe tasks on the machine's four cores at once, instead of running one task at a time. Using this method, 1000 tasks will run in the time that it takes to run 250 single tasks.

Using IncrediBuild, you can create a Profile, in the form of an XML file, which specifies to IncrediBuild how to process the different tasks (processes) in the application. As RenderApp, the main application, runs on the local machine, and is the invoker of sub-processes, you can define it in the Profile XML with AllowIntercept=true. Also, as RenderTask is to be run on a remote machine, you can define it as a remote task.

Note:

RenderApp.exe AllowIntercept=true
RenderTask.exe AllowRemote=true

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<Profile FormatVersion="1">
    <Tools>
        <Tool Filename=" RenderApp" AllowIntercept="true" />
        <Tool Filename=" RenderTask" AllowRemote="true" />
            </Tools>
</Profile>

IncrediBuild’s work flow for this example is as follows:

  1. IncrediBuild executes the main process RenderApp.exe.
  2. IncrediBuild intercepts all calls, which relate to process invocation that RenderApp.exe is to perform, and compares them to the list of processes that are marked in the profile.xml file as “AllowRemote=true”.
  3. When IncrediBuild encounters a process invocation that is marked in the process as AllowRemote=true, the IncrediBuild engine distributes this process to a remote machine instead of executing it locally.
  4. Any output generated by the remotely executed process is forwarded to the local machine (Initiator) as though it was executed on one of the local cores.

To further accelerate execution of RenderApp, it is recommended that instead of running RenderApp 1-1000 –cores4, to run the command

IBConsole RenderApp.exe 1-1000 -cores1000 /profile=profile.xml
This causes 1000 tasks to enter the IncrediBuild queue, with IncrediBuild managing the execution of the tasks according to the number of available cores. For example, if 200 cores are available, it runs 200 tasks at a time, thus finishing to run all 1000 tasks in the amount of time it takes to run five tasks.