• Other Features
  • Error, Warning and Info Messages
  • Explicit flow control commands
  • Re-using objects
  • Overriding parameter values

Other Features

Error, Warning and Info Messages

The base class coModule delivers a set of methods to send messages to the users. Info messages are displayed in the info box at the bottom of the Map Editor, warnings and errors in a pop-up window can be configured to pop up a window. The difference between warnings and errors is that after a module has issued an error, no other modules will execute automatically, while warnings only pop up without any impact on the flow control.

The programming interface of the message commands only differs in the endings:

Function names	Meaning
coModule::sendInfo	Info message
coModule::sendWarning	Warning message
coModule::sendError	Error message

static void coModule::sendWarning(const char *fmt, ...);
Description:	Send messages to the user interface
IN:	fmt	Message format string

All of the above message methods accept printf style arguments.

Explicit flow control commands

The control message passing is done internally in the module base class, usually none of the messages has to be sent by the user himself. Nevertheless, users might send own messages for explicit flow control to achieve effects that extend the classical data flow paradigm. Since these explicit calls violate the basic structure of the COVISE system, it is discouraged to use these calls. Explicit flow control calls can both influence stability and performance of the COVISE system and should be used by experienced users only and with special care for internal racing conditions.

Explicitly stopping the pipeline

The function void Covise::send_stop_pipeline() explicitly demands that no other modules be started automatically by the controller. It is discouraged to use this function: sendError accomplishes the same effect and also submits an error message. In all other than error cases the pipeline should run based on object creation and module connections.

Implicitly stopping pipeline execution

A module can prevent down-stream modules from being activated by not creating an output object. Any module is supposed to stop if a connected port receives no data. Using the classic module interface from earlier versions, this was the case when an object name was received, but no object could be retrieved based on this name. All modules created based on coModule automatically implement this behavior.

Self-execution

Any module callback (except compute) can tell the module that it should `execute' after the callback has been left. To achieve this, the function calls void coModule::selfExec(). Multiple calls within a callback will only trigger a single start. Warning: Executing a module again while the succeeding module is still running may cause COVISE to crash.

To prevent 'overrun' crashes, the module waits one second after the selfExec call has been submitted. This period can be configured by placing an entry `execGracePeriod' (measured in seconds) into the 'System.HostInfo' section of the configuration files or with the call coModule::setExecGracePeriod(float gracePeriod).

Re-using objects

Usually, COVISE objects have an automatic life period: They are created by a module and are destroyed when they are not needed any more. Nevertheless, COVISE makes some assumptions about the object usage:

• Objects read once at an input port are not used any further
• An object created in a module is either put ONCE into an output port or put ONCE into a Set or Geometry container

If a user wants to violate these assumption, he must tell the object that it is used more than once by incrementing its reference counter. This can be useful to

• "hand through" an object from an input to an output port by adding it to a container object
• add an input object to a container and give this to the output
• add an object more than once to a container - e.g. for a constant part within a time series.

To increment the reference counter, call:

coDistributedObject::incRefCount()
Description:	add a reference to a distributed object
Return value	number of references

Overriding parameter values

You may use the class coHideParam in order to override the values of some module parameters. For instance, you may wish to adjust the behaviour of the module not by directly modifying the module params, but rather let the module read their values from a string that the module may get for instance through a Text object at an input port, or that may be alternatively accessible as the value of some attribute given to one of the input objects. The example below should make it clear how this coHideParam class is used:

myModule.h

class myModule
{
   private:

      coBooleanParam *p_OneBooleanParam_;
      coFloatParam *p_OneFloatScalarParam_;
      coFloatVectorParam *p_OneIntVectorParam_;

      coHideParam *h_distance_of_plane_;
      coHideParam *h_OneFloatScalarParam_;
      coHideParam *h_OneIntVectorParam_;
      std::vector<coHideParam *> hparams_; // a useful container 
                                      // for the previous
                                      // coHideParam pointers
   
}

myModule.cpp

void
myModule::postInst()
{
   // create the hiding objects here 
   // and keep pointers in the container
   hparams_.push_back(h_OneBooleanParam_ = 
                      new coHideParam(p_OneBooleanParam_));
   hparams_.push_back(h_OneFloatScalarParam_ = 
                      new coHideParam(p_OneFloatScalarParam_));
   hparams_.push_back(h_OneIntVectorParam_ = 
                      new coHideParam(p_OneIntVectorParam_));
}


myModule::myModule()   // ... build ports and parameters as usual
{
  // create params here
  p_OneBooleanParam_ = addBooleanParameter("OneBooleanParamName",
                                           "a bool param");
  p_OneFloatScalarParam_ = 
         addFloatParameter("OneFloatScalarParamName",
                                         "a float scalar param");
  p_OneIntVectorParam_ = 
         addFloatParameter("OneIntVectorParamName",
                                         "an int vector param");
 
  // and set default values
  ....
}

#include <stringstream>

myModule::compute(const char *)   
{
  // RESETTING HIDING OBJECTS
  // first of all reset all hparams_
  for(int param = 0;param<hparams_.size();++param){
     hparams_[param]->reset();
  }
  ...

  char *values;
  ...

  // OVERRIDE PARAMETER VALUES (LOADING coHideParam OBJECTS)
  // assume that after the previous lines 
  // 'values' points to the string:
  // "OneBooleanParamName 0\nOneFloatScalarParamName 3.47\n
  //  OneIntVectorParamName 2 5 3\n"
  char *oneValue = new char[strlen(values)+1];
  istringstream pvalues(values);
  while(pvalues.getline(oneValue,strlen(values)+1)){
     for(int param=0;param<hparams_.size();++param){
        hparams_[param]->load(value);
     }
  }
  delete [] value;
  ...
  ...

  // AND NOW WE USE THE coHideParam OBJECTS 
  // INSTEAD OF THE PARAMETERS
  // whenever you would normally use a port, ...
  //     float notThisWay = 
  //                   p_OneFloatScalarParam_->getValue();
  // ...you use now instead the pertinent
  // coHideParam object
  float ratherThisWay = h_OneFloatScalarParam_->getFValue(); // 3.47
  int intArray[3];
  intArray[0] = h_OneIntVectorParam_->getIValue(0); // 2
  intArray[1] = h_OneIntVectorParam_->getIValue(1); // 5
  intArray[2] = h_OneIntVectorParam_->getIValue(2); // 3
  if(h_OneBooleanParam_->getIValue()){ // the returned value is 0
     ...
  }
}

Some remarks are here in order. Using the reset() member function for all coHideParam objects should always be done before using load(). After resetting, the object forgets previously assigned values, and if a value is requested using one of the getIValue or getFValue functions, the requested value will be that of the hidden parameter, i. e. the parameter that was indicated in the constructor of the coHideParam object (see myModule::postInst()).

Hiding parameter values is achieved when using the load() member function as used in the example. When the string values contains no substring for a given parameter, the corresponding coHideParam object will not hide that parameter. Otherwise, it will take the values that follow the parameter name.

If you are deriving myModule from coSimpleModule instead of coModule, you may prefer performing the resetting and loading of coHideParam objects in preHandleObjects and not in the compute function.

The last part concerns requesting values from these objects. For this purpose you have the following member functions at your disposal:

class coHideParam{
public:
   ...

   // get the float value 
   // when hiding coFloatParam or coFloatSliderParam
   float getFValue();

   // get the int value 
   // when hiding coChoiceParam, coBooleanParam, 
   // coInt32Param or coIntSliderParam
   int getIValue();

   // get the float value 
   // when hiding coFloatVectorParam
   float getFValue(int component);

   // get int values 
   // when hiding coFloatVectorParam
   int  getIValue(int);

   // get float values when hiding 
   // coFloatVectorParam (assuming 3 components)
   void getFValue(float &data0, float &data1, float &data2);
}

Previous

Next