The Embedded Executor

The "Embedded Executor" (EE) is the name of a special service that allows you to start multiple federates in the same JVM as Portico itself. Using the JVM binding, these federates will execute in separate threads but still share the same memory space as the RTI execution.

Advantages of Embedding
Embedded federates present many performance advantages over the traditional fully distributed approach. As all federates are executing in the same JVM, network communication latency is reduced to nothing. In the vast, vast majority of circumstances, network communication is the most time-intensive process that the RTI and federates engage in. Removing this bottleneck allows dramatically increased speeds.

In an effort to increase performance, the computing hardware industry has begun the move towards multi-core chips. As each federate is executing in a separate thread, such hardware can be more fully utilised, reducing any potential performance hit that the processing of multiple federates in a single execution might involve. Coupled with the lack of network I/O bottlenecks, significant performance gains can be realised.

Finally, just because you are using the embedded executor, it doesn’t exclude non-local federates from running in the same federation. You can get the best of both worlds by embedding I/O intensive federates while sticking with the traditional distributed framework for CPU intensive ones.

What does the Embedded Executor do?
The EE isn’t anything special, all it does is start the RTI and then create and start separate threads for each federate. If you want, you can write your own main method that embeds a Portico execution and start your own federates or other services manually (see Embedded Portico).

The only special facility the executor provides is automatic shutdown when all the embedded federates have finished*. The EE will monitor each of the federate threads it has started, and when they have all finished, it will shut Portico down. Above all else, the EE is just a convenience.


 * There is a switch to turn this off if you want to keep the RTI alive one all the embedded federates have finished. It is the –fed:noShutdown.

Using the Embedded Executor
To start the EE, you will need to use the specially provided startup script (or batch file):

[tim@moby portico-0.7]$ ./bin/portico-embedded

The listing above doesn't do anything special. In fact, it is equivalent to starting Portico through the usual mechanism. As we are not specifying any federates to run, the RTI will shutdown right away.

To start federates in an embedded execution, you must give the EE the fully qualified names of the main classes for the federates. These classes must have the typical public static void main Java method (see the section below), otherwise the EE won’t be able to fire them up. You specify to the EE which federates to start up through the –fed: command line argument:

[tim@moby portico-0.7]$ bin/portico-embedded -fed:mypackage.MyFederate -fed:com.example.SomeOtherFederate --verbose

In this example, the EE will start two separate threads; one for each class identified. It is also important to notice that you can pass regular Portico command line arguments to the EE. These will be passed on to Portico as if you were starting it normally. Thus, in the listing above, Portico would start up in verbose mode. The only exception to this rule is the –fed:noShutdown command line argument, which will only ever be interpreted by the EE.

IMPORTANT CLASSPATH NOTE: ''So that Java can find the code for your federates, you must put it in the plugins directory under your RTI_HOME (see Installing Portico). Ideally, your code will be in a jar file, but as that directory is added to the classpath itself, you can copy your .class files in there and they will be found.''

While passing the class names of federates to the EE via the command line is adequate in most cases. There are situations in which you may wish to pass command line arguments to an individual federate. The EE will pass any arguments it does not recognize onwards to Portico. As such, the command line argument method won’t provide this facility.

To fill this gap, the EE allows you to identify a file that contains federate configuration information. Consider the listing below (taken from the etc/example.embedded file):


 * 1) This is an example configuration file for #
 * 2) an embedded federation. You can specify a #
 * 3) set of command line arguments to use when #
 * 4) starting a given federate as shown below. #
 * 1) starting a given federate as shown below. #

// as well as lines like this
 * 1) Lines like this are ignored

// start the MyFederate class with two arguments com.example.MyFederate argumentOne argumentTwo

// start the MyOtherFederate class with no arguments com.example.MyOtherFederate

// yet another federate some.package.SomeFederate --verbose --argument

This file will tell the EE to start three federates, passing two arguments to the first federate, none to the second and two to the last one. To pass this information to the EE, you would invoke it like so:

[tim@moby portico-0.6]$ bin/portico-embedded -file:etc/example.embedded -fed:com.example.TheFederate

Notice that you can mix configuration file information and direct-invocation style information together on the same command line. If you wish, you can specify as multiple configuration files also.

How do I write an embedded federate?
Embedded federates are no different from regular federates. The only requirement is that they have the standard Java main method. In fact, the EE doesn’t actually have any real notion of what a federate is! Given this, if there is some application you want to start and have run in the same JVM as Portico and any embedded federates, you just have to pass its fully qualified class name as if it were a federate. This may be useful if you were creating a "federation-in-a-box" and wanted to include some kind of control or monitoring GUI. Either way, if it has a main file, it can be started as a "federate".

Mixing embedded and non-embedded federates
There is one little trick that is required to mix embedded and non-embedded federates. As the EE will start the given federates in their own threads right away, the federate that you are depending on to create the federation must be embedded. Further, it must be listed first to ensure that it is executed first. Apart from that, there is no difference between starting Portico via the EE or starting it normally.

It is important to note that when all the embedded federates are over, the EE will try to shutdown the RTI. If you want to keep the RTI alive beyond the life of any federates you have specified, you can include the –fed:noShutdown command line argument.