OMKOutput.h

Go to the documentation of this file.

/*
 * This file is part of openMask � INRIA, CNRS, Universite de Rennes 1 1993-2002, thereinafter the Software
 * 
 * The Software has been developped within the Siames Project. 
 * INRIA, the University of Rennes 1 and CNRS jointly hold intellectual property rights
 * 
 * The Software has been registered with the Agence pour la Protection des
 * Programmes (APP) under registration number IDDN.FR.001.510008.00.S.P.2001.000.41200
 *
 * This file may be distributed under the terms of the Q Public License
 * version 1.0 as defined by Trolltech AS of Norway and appearing in the file
 * LICENSE.QPL included in the packaging of this file.
 *
 * Licensees holding valid specific licenses issued by INRIA, CNRS or Universit� de Rennes 1 
 * for the software may use this file in accordance with that specific license
 *
 */
#ifndef OutputHEADER
#define OutputHEADER

#include "OMKOutputNT.h"
#include "OMKAbstractFifo.h"
#include "OMKPolator.h"
#include "OMKName.h"
#include "OMKController.h"
#include "OMKSimulatedObject.h"
#include "OMKUnInitialisedOutputException.h"
#include "OMKCurrentActiveObject.h"
#include <typeinfo>

namespace OMK
{
  template< typename T > class OutputAlias ;

template< typename T >
class Output : public OutputNT 
{
   public :

   Output( const Name & outputName, 
           SimulatedObject & owner,
           const int historySize,
           OMK::Type::PolatorNT * polator = 0 ) ;

   virtual ~Output() ;


   virtual const T& get( int & distanceToExactValue,
                         const int precisionLevel,
                         const Date & deltaT,
                         T& calculatedResult ) const ;


   virtual const T& getLastExactValue() const ;

   
   virtual const Date & getDateOfLastExactValue() const ;


   virtual void set( const T& newValue, bool alwaysUpdate = false ) ;
   
 
   virtual void suggest( const T& suggestedValue ) ;


   virtual T& getNextPlaceHolder() ;

   virtual void setInPlace( const T& ) ;


   virtual void connectedMyself( InputNT * input ) ;


   virtual void disconnectedMyself( InputNT * input ) ;


  
   virtual void extract( std::istream & = std::cin ) ;

   virtual void insertInStream( std::ostream & = std::cout ) const ;


   virtual void pack( OutgoingSynchronisationMessage & ) const ;


   virtual void packAllValues( OutgoingSynchronisationMessage & ) const ;


   virtual void unpack( IncomingSynchronisationMessage & ) ;

   virtual void unpackAllValues( IncomingSynchronisationMessage & ) ;


   virtual void printDebuggingInformation( std::ostream & err ) const ;

   void printHistory() const ;

   virtual void empty() ;
   
   virtual void setUsedOutput( Output< T > * output ) ;

   virtual void setAlias( OutputAlias< T > * output ) ;

   virtual void unsetAlias() ;

   virtual Output< T > * getUsedOutput() const ;


   virtual OutputAlias< T > * getAlias() const ;


protected :
   virtual void setValidity( bool ) ;

   friend class OutputAlias< T > ;

   virtual const T& localGet( int & validiteRes,
                              const int niveauInterpol,
                              const Date & deltaT,
                              T& resultPlaceHolder ) const ;


   virtual void localInsert( std::ostream & = std::cout ) const ;

   OutputAlias< T > * _aliasOfOutput ;
   
   Output< T > * _usedOutput ;
 
   AbstractFifo < T > * _history ; 

   const Date & _date ;

public:
  OMK::Type::Polator < T > * _polator;

protected:
   std::list<Input < T > *> _listOfConnectedUnsensitiveInputs;

#ifdef _OMK_MUTEX_
   OMKMutexLock _myMutex ;
#endif

   bool _validity ;
} ; // Output

} // namespace OMK


//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------


#include "OMKOutputAlias.h"

namespace OMK
{

//-----------------------------------------------------------------------------

template< typename T >
inline Output< T >::Output( const Name & outputName,
                            SimulatedObject & owner,
                            const int historyLength,
                            OMK::Type::PolatorNT * polator )
  : KernelAttribute( owner, outputName ),
    OutputNT( owner, outputName ),
     _aliasOfOutput( 0 ),
     _date( owner.getController().getSimulatedDate() ),
     _validity( false )
{
   /* Thread safety assessement : 
    * thread safe because only on construction of the object
    */

  if( polator == 0 )
  {
    // any type has a static method that creates a default polator
    T aTypeInstance ; // because createPolator isn't static
    _polator = static_cast< OMK::Type::Polator< T > * >(
      aTypeInstance.createPolator() ) ;

    if( _polator != 0 )
    {
      OMTRACEID( OMK_DEBUG_OMK_POL,
                 "Created default polator for output \""
                 << getName() << "\" of object \""
                 << owner.getName() << "\", with type "
                 << typeid( _polator ).name() ) ;
    }
    else
    {
      OMERROR( "Created default polator for output \""
               << getName() <<  "\" of object \""
               << owner.getName() << " is not of type \""
               << " OMK::Type::Polator <"
               << typeid( T ).name() << "> *\"" ) ;
    }
  }
  else 
  {
    _polator = dynamic_cast< OMK::Type::Polator< T > * >( polator ) ;
    if( _polator != 0)
    {
      OMTRACEID( OMK_DEBUG_OMK_POL,
                 "Given polator for output \""
                 << getName() << "\" of object \""
                 << owner.getName() << "\", with type "
                 << typeid( _polator ).name()
                 << " has been associated with this output" ) ;
    }
    else
    {
      OMERROR( "Created polator for output \""
               << getName() <<  "\" of object \""
               << owner.getName() << " is not of type \""
               << " OMK::Type::Polator <"
               << typeid( T ).name() << "> *\"" ) ;
    }
  }
  if( _polator == 0 )
  {
    OMFATALERROR( "No polator has been made for output \""
                  << getName() << "\" of object \""
                  << owner.getName() << "\"" ) ;
  }

  // calculate the appropriate history fifo length
  int realSize =
    historyLength + _polator->getNumberOfNeededValuesForMaxPrecisionPolation() ;
  _history = new Fifo< T >( realSize ) ;
  _polator->setFifo( _history ) ;

  _usedOutput = this ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline Output< T >::~Output()
{
  /* Thread safety assessement :
   * thread safe because only one destruction of the object
   */
#ifdef _OMK_MUTEX_
  _myMutex.protect() ;
#endif

  typename std::list< Input< T > * >::iterator j ;
  for( j = _listOfConnectedUnsensitiveInputs.begin() ;
       j != _listOfConnectedUnsensitiveInputs.end() ;
       j++ )
  {
    (*j)->outputDestroyed() ;
  }

#ifdef _OMK_MUTEX_
  _myMutex.unprotect() ;
#endif

  if( _aliasOfOutput != 0 )
  {
    _aliasOfOutput->aliasedOutputDeleted() ;
  }
  delete _history ;
}

//-----------------------------------------------------------------------------

template <class T>
inline void Output< T >::setUsedOutput( Output< T > * output )
{
   /* Thread safety assessement :
    * multiple simultaneous access possible, and doesn't compromise thread
    * safety : last one out wins
    */
  _usedOutput = output ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::setValidity( bool b )
{
  /* Thread safety assessement :
   * protected method, used to change protected member : thread safety should
   * be insured by callers 
   */
  _validity = b ;
}

//-----------------------------------------------------------------------------

template< typename T > 
inline void Output< T >::unsetAlias()
{
  /* Thread safety assessement :
   * multiple simultaneous access possible, but they don't compromise thread
   * safety : last one out wins     
   */
  _aliasOfOutput = 0 ;
  setUsedOutput( this ) ;
}

//-----------------------------------------------------------------------------

template< typename T > 
inline void Output< T >::setAlias( OutputAlias< T > * output )
{
   /* Thread safety assessement :
    * multiple simultaneous access possible, but they don't compromise thread
    * safety : last one out wins     
    */
  _aliasOfOutput = output ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline Output< T > * Output< T >::getUsedOutput() const
{
   /* Thread safety assessement :
    * protected method
    * multiple simultaneous access possible, but as long as this method is only
    * used onced by each access patern, the OMKOutput stays coherant   
    */
  return _usedOutput ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline OutputAlias< T > * Output< T >::getAlias() const
{
  /* Thread safety assessement :
   * protected method
   * multiple simultaneous access possible, but as long as this method is only
   * used onced by each access patern, the OMKOuptut stays coherant   
   */
  return _aliasOfOutput ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline const T& Output< T >::get( int & validiteRes,
                                  const int niveauInterpol,
                                  const Date & deltaT,
                                  T& resultPlaceHolder ) const
{
  /* Thread safety assessement :
   * As thread safe as localGet   
   */
#ifdef _DEBUGTYPEUTIL
  std::cerr << "Output< T >::get" << std::endl ;
  std::cerr << "used Output: "<< getUsedOutpute() << std::endl ;
  std::cerr << "file: " << _history << std::endl ;
  _history->printDebuggingInformation() ;
  informations() ;
#endif
   OMASSERT( getUsedOutput() != 0 ) ;
   return getUsedOutput()->localGet(
     validiteRes, niveauInterpol, deltaT, resultPlaceHolder ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
const T& Output< T >::localGet( int & validiteRes,
                                const int niveauInterpol,
                                const Date & deltaT,
                                T& resultPlaceHolder ) const
{   
  /* Thread safety assessement :
   * As thread safe as polate from OMKInterplateur. But be careful : in a
   * multithreaded environment this member function can generate more
   * exceptions than expected 
   */
  touch() ;
  if( !_validity )
  {
    throw UnInitialisedOutputException( *this, "Output< T >::localGet \n" ) ;
  }

#ifdef _DEBUGTYPEUTIL
  std::cerr << "Output< T >::localGet" << std::endl ;
  std::cerr << owner.getController().getSimulatedDate() << std::endl ;
  std::cerr << "Interpolateur : "<< _polator << std::endl ;
#endif
  Date date = _owner.getController().getSimulatedDate() - deltaT ;
  return _polator->polate(
    niveauInterpol, date, validiteRes, resultPlaceHolder ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::connectedMyself( InputNT * input )
{
  /* Thread safety assessement : 
   * Critical data is mutex protected  
   */
  touch() ;
#ifdef _OMK_MUTEX_
  _myMutex.protect() ;
#endif

  Input< T > * standardInput = dynamic_cast<Input< T > * >( input ) ;
  OMASSERT( standardInput != 0 ) ;
  _listOfConnectedUnsensitiveInputs.push_back( standardInput ) ;

#ifdef _OMK_MUTEX_
  _myMutex.unprotect() ;
#endif
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::disconnectedMyself( InputNT * input )
{
#ifdef _DEBUGALIAS
  std::cerr << "Output< T >::disconnectedMyself" << std::endl ;
#endif

  /* Thread safety assessement :
   * critical data is mutex protected  
   */
#ifdef _OMK_MUTEX_
  _myMutex.protect() ;
#endif

  Input < T > * unsensitiveInput = dynamic_cast< Input < T > * >( input ) ;
  _listOfConnectedUnsensitiveInputs.remove( unsensitiveInput ) ;

#ifdef _OMK_MUTEX_
  _myMutex.unprotect() ;
#endif
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::set( const T& newValue,
                              bool alwaysUpdate /*= false*/ ) 
{
#ifndef NDEBUG
  if( CurrentActiveObject::getCurrentActiveObject() != &_owner
   && CurrentActiveObject::getCurrentActiveObject() != &_owner.getController()
   && CurrentActiveObject::getCurrentActiveObject() )
  {
    OMERROR( ":-( Error in Output<" << typeid( T ).name() 
             << ">::set:  Unable to set the output \""
             << getName().getString() << "\""
             << std::endl
             << "The output owner [" << _owner.getName()
             << "] is not the active object ["
             << ( CurrentActiveObject::getCurrentActiveObject() ? 
                  CurrentActiveObject::getCurrentActiveObject()->getName().getString() :
                  std::string( "no active object" ) )
             << "]" ) ;
  }
#endif

  /*OMASSERT( &_owner == CurrentActiveObject::getCurrentActiveObject() 
            || CurrentActiveObject::getCurrentActiveObject() == & _owner.getController()
            || CurrentActiveObject::getCurrentActiveObject() == 0 ) ;*/
  /* Thread safety assessement :
   * localGet and set could collide. Thread safety can only be assured if the
   * fifo and the interpolator are thread safe with respect to the value in the
   * fifo.
   * Only one set at a time.
   */
  _history->set( newValue, _date ) ;
  setValidity( true ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::extract( std::istream & in )
{
  /* Thread safety assessement :
   * localGet and extract could collide. Thread safety can only be assured if
   * the fifo and the interpolator are thread safe with respect to the values
   * in the fifo.
   * Only one extract at a time.
   */
  in >> *_history ;
  setValidity( true ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::pack( OutgoingSynchronisationMessage & out ) const
{
  //std::cerr << "Output< T >::pack" << std::endl ;
  //packs the name of the output, then any usefull information
  /* Thread safety assement :
   * Thread safe : collides with set and localInsert on the AbstractFifo. But
   * they should only be activated by the owner. So as long as the owner isn't
   * multithreaded...
   * Nota : in a multithreaded environment this member function could generate
   * more exceptions than expected
   */
  if( _validity && out.getMessageDate() == _history->getPreceedingDate( 0 ) )
  {
    getName().pack( out ) ;
    _history->pack( out ) ;
  }
  //else : do not pack anything, therefore mirror will remain uninitialised
  //std::cerr << "Output< T >:" << this << ":pack done" << std::endl ;
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::packAllValues( OutgoingSynchronisationMessage & out ) const
{
  //std::cerr<<"packAllValues output \"" << getName() << "\"" ) ;
  //packs the name of the output, then all initial information
  /* Thread safety assement :
   * Thread safe : collides with set and localInsert on the AbstractFifo. But
   * they should only be activated by the owner. So as long as the owner isn't
   * multithreaded, or that the kernel doesn't call this member function during
   * activation of the owner...
   * Nota : in a multithreaded environment this member function could generate
   * more exceptions than expected
   */
  if( _validity )
  {
    getName().pack( out ) ;
    _history->packAllValues( out ) ;
  }
  //else : do not pack anything, therefore mirror will remain uninitialised
  //std::cerr<<"Output< T >:" << this << ":packAllValues done" << std::endl ;
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::unpack( IncomingSynchronisationMessage & in )
{
  // shouldn't unpack the name, but all other usefull information packed
  /* Thread safety assessement : 
   * localGet and extract could collide. Thread safety can only be assured if
   * the fifo and the interpolator are thread safe with respect to the values
   * in the fifo.
   * Only one extract at a time.
   */
  _history->unpack( in ) ;
  setValidity( true ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
void Output< T >::unpackAllValues( IncomingSynchronisationMessage & in )
{
  // shouldn't unpack the name, but all other usefull information packed
  /* Thread safety assessement : 
   * localGet and extract could collide. Thread safety can only be assured if
   * the fifo and the interpolator are thread safe with respect to the values
   * in the fifo.
   * Only one extract at a time.
   */
  _history->unpackAllValues( in ) ;
  setValidity( true ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::insertInStream( std::ostream & out ) const
{
  /* Thread safety assessement :
   * As thread safe as localInsert 
   */
  getUsedOutput()->localInsert( out ) ; 
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::localInsert( std::ostream & out ) const
{
  /* Thread safety assement
   * Thread safe : collides with set on the AbstractFifo. But they should only
   * be activated by the owner. So as lmong as the owner isn't multithreaded...
   * Nota : in a multithreaded environment this member function could generate
   * more exceptions than expected
   */
  if( !_validity )
  {
    UnInitialisedOutputException exception( *this,
                                            "Output< T >::localInsert\n" ) ;
    exception << "Cannot read uninitailised output of "
              << _owner.getName().getCString() ;
    throw exception ;
  }
  else 
  {
    out << *_history << " " ;
  }
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::printHistory() const
{
  /* thread safety assessement :
   * const method : should be thread safe if printDebuggingInformation of
   * AbstractFifo is thread safe
   */
  _history->printDebuggingInformation() ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::printDebuggingInformation( std::ostream & err ) const
{
   /* thread safety assessement :
    * const method : thread safe. shown value may not be a coherant image of
    * an Output
    */
  err << std::endl
      << "**********************************************************"
      << std::endl
      << "Class Output" << std::endl
      << "Owner : " << _owner.getName() << std::endl
      << "Output Name : "<< _name << std::endl
      << "T of output : "<< typeid( T ).name() << std::endl 
      << "Output primary alias : " << getAlias() << std::endl 
      << "Used Output : " << getUsedOutput() << std::endl 
      << "History Fifo: " << _history << std::endl ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::empty()
{
  /* Thread safety assessement :
   * as thread safe as clear of fifo. Only one simultaneous acces possible (in
   * theory).
   */
  _history->clear() ;
  setValidity( false ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline const T& Output< T >::getLastExactValue() const
{
  touch() ;
  // this bypasses any Polator
  if( _history->getNumberOfPresentValues( 1 ) < 1 ) // if no value is stored
  {
    UnInitialisedOutputException exception(
      *this, "Output< T >::getLastExactValue\n" ) ;
    exception << "Impossible to get a value from an uninitialised output of "
              << _owner.getName().getCString() ;
    throw exception ;
  }
  return _history->getPreceedingValue( 0 ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline const Date & Output< T >::getDateOfLastExactValue() const
{
   touch() ;
   // this bypasses any Polator
   if( _history->getNumberOfPresentValues( 1 ) < 1 ) // if no value is stored
   {
     UnInitialisedOutputException exception(
       *this, "Output< T >::getLastExactValue\n" ) ;
     exception << "Impossible to get a value from an uninitialised output of "
               << _owner.getName().getCString() ;
     throw exception ;
   }
   return _history->getPreceedingDate( 0 ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline T& Output< T >::getNextPlaceHolder()
{
  return _history->getNextPlaceHolder() ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::setInPlace( const T& newValue )
{
  _history->setInPlace( newValue, _date ) ;
  setValidity( true ) ;
}

//-----------------------------------------------------------------------------

template< typename T >
inline void Output< T >::suggest( const T& newValue )
{
  if( !_validity )
  {
    _history->set( newValue , _owner.getController().getSimulatedDate() ) ;
    setValidity( true ) ;
  }
}

//-----------------------------------------------------------------------------

} // namespace OMK

#endif

---