Cookbook

This page explains how to use Ishtar settings by example.

Simple variables from simple config file

Ishtar settings provides the user with variables that act like C++ ones excepted that:

• They have an Ishtar name in addition to their C++ name.
• Their initial values are read from a config file.
• They are network accessible using Ishtar services protocol.
• They are global, i.e. if two variables have the same Ishtar name, they will always have the same value and if one is changed, the other is automatically updated.
• They are implicitely vectors. In fact, those variables are subclasses of Ishtar::Service (see libishtarservices documentation for details).

Initializing Ishtar settings

To use Ishtar settings, you need the following program structure:

// Include Ishtar settings
#include <ishtar/settings.h>

[...]

int main(int argc, char *argv[])
{
    // Init settings before doing anything
    Ishtar::initSettings(argc, argv);
    
    [...]
    
    // Program loop
    while (condition)
    {
        [...]
        
        // Let Ishtar perform network operations
        Ishtar::settings->step();
        
        [...]
    }
    
    [...]
    
    // Cleanup settings after all variables are destroyed
    Ishtar::cleanupSettings();
}

The argc, argv parameters are used by Ishtar to potentially select another port (with the -p PORT command line argument). They are optional. Don't forget to call Ishtar::settings->step() often enough otherwise Ishtar will not serve network queries.

Loading config files

Config files can be loaded through Ishtar::settings which is a global pointer to Ishtar::Settings.

Ishtar::settings->loadConfigFile("config file name");

Declaring variables

It is then possible to declare an Ishtar::Variable using the three parameters:

• T, the type of the variable (mandatory)
• ro, the read-only/read-write mode (default: false)
• s, the size of the vector(default: 1)

Ishtar::Variable<T,ro,s> variable("ishtar name", defaultValue);

A complete example

The code sample below will read the value (1.0) of variable timeStep from a config file named "settings.txt" in text format.

settings.txt:

timeStep = 1.0;

testishtarsettings.cpp:

#include <ishtar/settings.h>
#include <iostream>

int main(int argc, char *argv[])
{
    Ishtar::initSettings(argc, argv);
    
    // Load config file in text format containing the default value of variable timeStep
    Ishtar::settings->loadConfigFile("settings.txt");
    
    // New scope because all Ishtar variables have to be destroyed before Ishtar::cleanupSettings is called
    {
        // Ishtar variable, C++ name timeStep, Ishtar name "timeStep", default value = 0.0
        Ishtar::Variable<double> timeStep("timeStep", 0.0);
    
        // Print variable value
        std::cout << "Initial timeStep is " << timeStep << std::endl;
        timeStep += 1.0;
        std::cout << "Final timeStep is " << timeStep << std::endl;
    }
    
    Ishtar::cleanupSettings();
}

You can then compile this program, assuming its name is testishtarsettings.cpp, with the following command:

g++-3.4 testishtarsettings.cpp -o testishtarsettings -lishtarsettings -lishtarservices -lishtarnet

and launch it:

./testishtarsettings

Advanced config file

Several advanced features are available in config files:

• Comments
• Array variables
• Hierarchical naming
• Autovectors

The config file and code sample below illustrate this:

advancedsettings.txt:

// comment, multi-line C++ comments are also available / *  * /

// variable that is not scalar, but array (in this case of size 3)
arrayVariable = 1 2 3;

universe
{
    earth
    {
        // hierarchical naming. Full name is "universe.earth.population",
        // "universe.earth" is named by convention as the root of this subsection.
        population = 6e9; 
    }
}

// "objects" contains three sections with no name.
// They will be named automatically by increasing numbers and an
// additional variable "objects.count" with value 3 will be created.
// This behaviour is known as autovector.
objects
{
    // this section has no name, it will be automatically named 0
    {
        size = 3;
    }
    // this section has no name, it will be automatically named 1
    {
        size = 1;
    }
    // this section has no name, it will be automatically named 2
    {
        size = 4;
    }
}

excerpt of code:

// Array variables
Ishtar::Variable<unsigned, false, 3> arrayVariable("arrayVariable", 0);

// Hierarchical naming
Ishtar::Variable<double> earthPop("universe.earth.population", 0.0);

// Autovectors
// Array helper is a class that reads autovectors...
Ishtar::ArrayHelper arrayHelper("objects");
// ...it knows the number of elements...
std::cout << "Number of elements in autovector = " << arrayHelper.getMaxIndex() << std::endl;
// ...and can return the root of a given index...
std::string firstElement = arrayHelper.getRoot(0);
// ...to which we can now add a setting name...
firstElement += ".size";
// ...that can be used to initialize a variable...
Ishtar::Variable<double> firstElementSize(firstElement, 0.0);
// ...that we can read!
std::cout << "Size of first element = " << firstElementSize << std::endl;

Other types of variables

Until now, we have talked only about variables whose values were in Ishtar's control. This is not always possible: In some case, one would like to make available through Ishtar variables which already exist, for instance from a struct of an external library.

To that end, Ishtar provides Ishtar::VariablesPublisher, which is an object that can be instantiated with a root, and to which variables can be added. Those variables have nevertheless some limitations:

• They are not global: Each variable added to the publisher is a new variable from the Ishtar viewpoint.
• They are not garbage collected: Each variable added to the publisher exists until the publisher is destroyed. If the target (C++ one) variable is destroyed before the publisher, a memory trash occurs.

The following code sample illustrates how to use a publisher:

// Some C++ variables
double radius;
double coord[2];

// Create a publisher with root "objects.circle"
Ishtar::Publisher ishtarPublisher("objects.circle");

// Add some variable, initialised with values from config files (if they exists) and registered by Ishtar
ishtarPublisher.add<double, false, 1>(&radius, "radius");
ishtarPublisher.add<double, false, 2>(coord, "coordinates", Ishtar::StringsAccumulator() + "x" + "y");

---