Using Automatic Interception Interfaces

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.

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). 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:

• <TOOL COMMAND>–the command line string used to run the tool with the parallel process execution mode enabled

• <PROFILE XML>–the Profile XML file

• Other Options–Refer to the IBConsole Command Reference section for more IBConsole.exe command line options.As an alternative to using a Profile XML file, it is possible to specify the AllowIntercept and AllowRemote directives explicitly in the IBConsole command line:

  IBConsole.exe /command="<TOOL COMMAND>" /allowremote="<FILENAME1[,FILENAME2,...]>" /allowintercept="<FILENAME1[,FILENAME2,...]>" [Other Options]

Where:

• <TOOL COMMAND>–the command line string used to run the tool with the parallel process execution mode enabled

• <FILENAME1[,FILENAME2,...]>–a comma-separated list of tool filenames

• Other Options- Refer to the IBConsole Command Reference section for more IBConsole.exe command line options.

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: You are not required to install anything on the remote machine, and also do have to upload any files to it. Incredibuild processes the tasks as if the cores on the remote machine are on on the local machine.

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.

You are welcome to look at our sample projects under the Incredibuild installation folder in Samples\Dev Tools Interfaces Usage Samples\Interception Interface. One such sample is Sample Project, which demonstrates a simple automatic interception sample.

This sample requires the following parameters:

• The exe to run (DummyProcess.exe)

• The number of times to execute the process

• The sleep time before killing the processes

• [optional] The time until the sub-process kills itself

Automatic Interception Interface Sample Project:

The following sample demonstrates a job in which a process having the name MainProcess executes many sub-processes having the name Dummy.

The XML file in the following sample is saved as Profile.xml.

IBConsole /command="MainProcess.exe DummySubProcess.exe 10 2000 2000" /profile="profile.xml" /openmonitor /title="Automatic Interception Sample"

In this example, MainProcess.exe accelerates in parallel 10 instances of DummySubProcess.exe, each running for two seconds. As the processes are defined in the profile as AllowRemote=true, they run on both the local and remote machines.