---

PsOutput.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 PsOutputHEADER
#define PsOutputHEADER

#include <PsOutputNT.h>
#include <PsnAbstractFifo.h>
#include <typeinfo>
#include <PsPolator.h>
#include <PsName.h>
#include <PsController.h>
#include <PsSimulatedObject.h>
#include <PsSensitiveInput.h>
#include <PsUnInitialisedOutputException.h>
#include <PsnMutexLock.h>

#include "PsnSystemMemoryManager.h"
#include "PsnCurrentActiveObject.h"

template <typename Type> class PsOutputAlias ;

template <typename Type>
class PsOutput : public PsOutputNT 
{
   public :

  PsOutput (const PsName & outputName, 
            PsSimulatedObject & owner,
            const int historySize,
            PsPolatorNT * polator = NULL ) ;

   virtual ~PsOutput (void) ;


   virtual const Type & get (int & distanceToExactValue,
                             const int precisionLevel,
                             const PsDate & deltaT,
                             Type & calculatedResult ) const ;


   virtual const Type & getLastExactValue () const ;

   
   virtual const PsDate & getDateOfLastExactValue () const ;

   
   virtual void set ( const Type & newValue ) ;
   
 
   virtual void suggest ( const Type & suggestedValue ) ;


   virtual Type & getNextPlaceHolder() ;

   virtual void setInPlace ( const Type & ) ;
      

   virtual void connectedMyself(PsInputNT * input) ;


   virtual void disconnectedMyself(PsInputNT * input) ;


  
   virtual void extract (istream & = cin) ;

   virtual void insertInStream (ostream & = cout) const ;


   virtual void pack (PsOutgoingSynchronisationMessage &) const ;


   virtual void packAllValues (PsOutgoingSynchronisationMessage &) const ;


   virtual void unpack (PsIncomingSynchronisationMessage &) ;

   virtual void unpackAllValues (PsIncomingSynchronisationMessage &) ;
  

   virtual void printDebuggingInformation ( ostream & err ) const ;

   void printHistory () const ;

   virtual void empty () ;
   
   virtual void setUsedOutput(PsOutput<Type>  * output)  ;

   virtual void setAlias(PsOutputAlias<Type> * output) ;

   virtual void unsetAlias () ;

   virtual PsOutput<Type> * getUsedOutput( void ) const ;


   virtual PsOutputAlias<Type> * getAlias ( void ) const ;


protected :
   virtual void setValidity(bool);

   friend class PsOutputAlias<Type> ;

   virtual void notifyConnectedSensitiveInputs();

   virtual const Type & localGet (int & validiteRes,
                                  const int niveauInterpol,
                                  const PsDate & deltaT,
                                  Type & resultPlaceHolder) const ;


   virtual void localInsert (ostream & = cout) const ;

   PsOutputAlias<Type> * _aliasOfOutput ;
   
   PsOutput<Type> * _usedOutput ;
 
   PsnAbstractFifo <Type> * _history ; 

   const PsDate & _date ;

public:
   PsPolator <Type> * _polator;

protected:
   list<PsSensitiveInput <Type> *> _listOfConnectedSensitiveInputs;

   list<PsInput <Type> *> _listOfConnectedUnsensitiveInputs;

   bool _sensitiveInputsConnected ;

   PsnMutexLock _myMutex ;

   bool _validity ;
} ; // PsOutput

#if defined(_MOME) || !defined(_SGI)
#include <PsMomeOutput.h>
#endif

//-----------------------------------------------------------------
#include "PsOutputAlias.h"

template <typename Type>
inline PsOutput<Type>::PsOutput (const PsName & outputName,
                                 PsSimulatedObject & owner,
                                 const int historyLength,
                                 PsPolatorNT * polator)
   : PsAttribute(owner, outputName),
     PsOutputNT (owner, outputName),
     _aliasOfOutput ( NULL ),
     _date ( owner.getController().getSimulatedDate() ),
     _sensitiveInputsConnected ( false ),
     _validity ( false )
{
   /* thread safety assessement : 
      thread safe because only on construction of the object
    */


#ifdef _DEBUGTYPEUTIL
   cout << "PsOutput<Type>::PsOutput () constructor" << endl;
#endif

  if ( polator == NULL )
     // tous les types ont une methode static qui crait leur polator par defaut
    {
       Type aTypeInstance ; // because createPolator isn't static

       _polator = static_cast<PsPolator <Type> *>(aTypeInstance.createPolator()) ; 

       if ( _polator==NULL ) 
          {
             cerr<<"PsOutput<"<<typeid(Type).name()<<">::PsOutput : the created polator of "
                 <<typeid(aTypeInstance).name()<<" isn't of type PsPolator <"<<typeid(Type).name()<<"> *"<<endl;
          }
    }
  else 
     {
        _polator = dynamic_cast<PsPolator <Type> *>(polator) ;

        if (_polator==NULL) 
           {
              cerr<<"PsOutput<"<<typeid(Type).name()<<">::PsOutput : the created polator of type "
                  <<typeid(polator).name()<<" isn't of type PsPolator <"<<typeid(Type).name()<<"> *"<<endl;
           }
     }
  if (_polator==NULL) 
     {  
        cerr<<"PsOutput<"<<typeid(Type).name()<<">::PsOutput : problem in creating the appropriate polator for output "<<getName()<<endl;
     }

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

  _usedOutput = this ;

}

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

template <typename Type>
inline PsOutput<Type>::~PsOutput (void)
{
   /* thread safety assessement : 
      thread safe because only one destruction of the object
    */

#ifdef _TYPENAMENOTIMPLICIT
   typename 
#endif
   list<PsSensitiveInput <Type> *>::iterator i;

   _myMutex.protect() ;

   for (i = _listOfConnectedSensitiveInputs.begin();
        i != _listOfConnectedSensitiveInputs.end();
        i++) 
      {
         (*i)->outputDestroyed();
      }

#ifdef _TYPENAMENOTIMPLICIT
   typename 
#endif
   list<PsInput <Type> *>::iterator j;

   for (j = _listOfConnectedUnsensitiveInputs.begin();
        j != _listOfConnectedUnsensitiveInputs.end();
        j++) 
      {
         (*j)->outputDestroyed();
      }

   _myMutex.unprotect() ;

   if ( _aliasOfOutput != NULL ) _aliasOfOutput->aliasedOutputDeleted () ;

   if ( _history != NULL ) delete _history ;
}

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

template <class Type>
inline void PsOutput<Type>::setUsedOutput(PsOutput<Type> * output) 
{
   /* thread safety assessement : 
      multiple simultaneous access possible, and doesn't compromise thread safety : last one out wins
   */

   _usedOutput = output ;
}

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

template <typename Type>
void PsOutput<Type>::setValidity(bool b) {
   /* thread safety assessement : 
      protected method, used to change protected member : thread safety should be insured by callers 
   */

   _validity = b ;
}

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

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


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

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

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

template <typename Type>
inline PsOutput<Type> * PsOutput<Type>::getUsedOutput( void ) 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 PsOuptut stays coherant   
   */
  return _usedOutput ;
}


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

template <typename Type>
inline PsOutputAlias<Type> * PsOutput<Type>::getAlias(void) 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 PsOuptut stays coherant   
   */
 return _aliasOfOutput ;
}

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

template <typename Type>
inline const Type & PsOutput<Type>::get(int & validiteRes,
                                        const int niveauInterpol,
                                        const PsDate & deltaT,
                                        Type & resultPlaceHolder ) const
{
    /* thread safety assessement : 
       As thread safe as localGet   
    */
#ifdef _DEBUGTYPEUTIL
   cerr<<"PsOutput<Type>::get"<<endl;
   cerr<<"OutputUtilisée : "<<getUsedOutpute()<<endl;
   cerr<<"file : "<<_history<<endl;
   _history->printDebuggingInformation() ;
   informations();
#endif
   assert( getUsedOutput () != NULL ) ;
   return getUsedOutput ()->localGet(validiteRes,niveauInterpol,deltaT,resultPlaceHolder);
}

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

template <typename Type>
const Type & PsOutput<Type>::localGet(int & validiteRes,
                                        const int niveauInterpol,
                                        const PsDate & deltaT,
                                        Type & resultPlaceHolder) const
{   
   /* thread safety assessement : 
      As thread safe as polate from PsInterplateur. But be careful : in a multithreaded environment this member function can generate more exceptions than expected 
   */
   touch() ;
   if (!_validity) 
      {
         HeapStackTop usualContext( HeapStackTop::getSystemMemoryManager() );
         PsUnInitialisedOutputException exception(*this,"PsOutput<Type>::localGet \n");
         throw exception;
      } 
   else 
      { 
#ifdef _DEBUGTYPEUTIL
         cerr<<"PsOutput<Type>::localGet"<<endl;
         cerr<<owner.getController().getSimulatedDate()<<endl;
         cerr<<"Interpolateur : "<<_polator<<endl;
#endif
         PsDate date = _owner.getController().getSimulatedDate() - deltaT ;
         return _polator->polate(niveauInterpol, date,validiteRes, resultPlaceHolder);
      }
}

template <typename Type>
void PsOutput<Type>::notifyConnectedSensitiveInputs() {

   /* thread safety assessement : 
      mutex protected  
   */
    if ( _sensitiveInputsConnected ) 
       {
          // with sensitive inputs connected, it is as if the output value was read at each step
          touch() ;
#ifdef _TYPENAMENOTIMPLICIT
   typename 
#endif
       list<PsSensitiveInput <Type> *>::iterator i;
       
       _myMutex.protect() ;
       
       for (i=_listOfConnectedSensitiveInputs.begin() ;
            i!=_listOfConnectedSensitiveInputs.end() ;
            i++ ) {
#ifdef _DEBUGALIAS
          cerr<<"PsOutput<Type>::notifyConnectedSensitiveInputs : one to notify"<<endl;
#endif
          (*i)->signalChange();
#ifdef _DEBUGALIAS
          cerr<<"PsOutput<Type>::notifyConnectedSensitiveInputs : one notified"<<endl;
#endif
       }
       _myMutex.unprotect() ;
    }
}

template <typename Type>
void PsOutput<Type>::connectedMyself(PsInputNT * input) {

   /* thread safety assessement : 
      critical data is mutex protected  
   */
   touch() ;
   PsSensitiveInput <Type> * inputSensible=dynamic_cast< PsSensitiveInput <Type> *>(input);
   if (inputSensible!=NULL) 
      {
#ifdef _DEBUGALIAS
      cerr<<"PsOutput<Type>::connectedMyself"<<input<<endl;
#endif
      _myMutex.protect () ;

      _listOfConnectedSensitiveInputs.push_back(inputSensible);
      
      _sensitiveInputsConnected = true ;

      _myMutex.unprotect () ;
   }
   else 
      {
         _myMutex.protect () ;

         PsInput<Type> * standardInput = dynamic_cast<PsInput<Type> *> (input) ;
         
         assert (standardInput != NULL ) ;
         _listOfConnectedUnsensitiveInputs.push_back ( standardInput ) ;

         _myMutex.unprotect () ;
      }
}


template <typename Type>
void PsOutput<Type>::disconnectedMyself(PsInputNT * input) {
#ifdef _DEBUGALIAS
   cerr<<"PsOutput<Type>::disconnectedMyself"<<endl;
#endif

   /* thread safety assessement : 
      critical data is mutex protected  
   */

   PsSensitiveInput <Type> * inputSensible=dynamic_cast< PsSensitiveInput <Type> *>(input);

   if (inputSensible!=NULL) 
      {
         
         _myMutex.protect () ;
         
         _listOfConnectedSensitiveInputs.remove(inputSensible);

         if ( _listOfConnectedSensitiveInputs.empty() ) _sensitiveInputsConnected = false ;
         
         _myMutex.unprotect () ;

      }
   else
      {

         _myMutex.protect () ;

         PsInput <Type> * unsensitiveInput = dynamic_cast< PsInput <Type> *>(input); 

         _listOfConnectedUnsensitiveInputs.remove(unsensitiveInput);
        
         _myMutex.unprotect () ;

      }
}

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

template <typename Type>
inline void PsOutput<Type>::set (const Type & newValue ) 
{

   assert (&_owner == PsnCurrentActiveObject::getCurrentActiveObject() || 
           PsnCurrentActiveObject::getCurrentActiveObject() == & _owner.getController() ||
           PsnCurrentActiveObject::getCurrentActiveObject() == NULL ) ;

   /* 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.
   */

   if (_validity) 
      {
         const Type & oldValue = _history->getPreceedingValue(0);
         if( newValue != oldValue ) //comparaison has to be done before the set, because we're working on references and that there can be a double set (bug corrected by D. Margery)
            {
               _history->set ( newValue, _date) ;
               notifyConnectedSensitiveInputs() ;
            }
         else 
            {
               _history->set ( newValue, _date) ;
            } 
   }
   else {
      _history->set (newValue, _date) ;
      setValidity(true) ;
      notifyConnectedSensitiveInputs();
   }   
} 

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

template <typename Type>
inline void PsOutput<Type>::extract (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.
   */

   if (_validity) 
      {  
         const Type & oldValue=_history->getPreceedingValue(0);
         in >> *_history ;
         if(_history->getPreceedingValue(0)!=oldValue) //double extract won't happen 
            {
               notifyConnectedSensitiveInputs();
            }
      }
   else 
      {
         in >> *_history ;
         setValidity(true) ;
         notifyConnectedSensitiveInputs();
      }
}

template <typename Type>
void PsOutput<Type>::pack (PsOutgoingSynchronisationMessage & out) const 
{
   //cerr<<"PsOutput<Type>::pack"<<endl;
   //packs the name of the output, then any usefull information
   /* thread safety assement
      thread safe : collides with set and localInsert on the PsnAbstractFifo. 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) 
      {
         if ( out.getMessageDate() == _history->getPreceedingDate ( 0 ) )
            {
               getName ().pack ( out ) ;
               _history->pack( out ) ;
            }
     }
   //else : do not pack anything, therefore mirror will remain uninitialised
   //   cerr<<"PsOutput<Type>:"<<this<<":pack done"<<endl;
}



template <typename Type>
void PsOutput<Type>::packAllValues (PsOutgoingSynchronisationMessage & out) const 
{
   //cerr<<"PsOutput<Type>::packAllValues"<<endl;
   //packs the name of the output, then all initial information
   /* thread safety assement
      thread safe : collides with set and localInsert on the PsnAbstractFifo. 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
   //   cerr<<"PsOutput<Type>:"<<this<<":packAllVAlues done"<<endl;
}



template <typename Type>
void PsOutput<Type>::unpack (PsIncomingSynchronisationMessage & 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.
   */

   if (_validity) 
      {  
         const Type & oldValue = _history->getPreceedingValue(0);
         _history->unpack ( in ) ;
         if(_history->getPreceedingValue(0) != oldValue) //double extract won't happen 
            {
               notifyConnectedSensitiveInputs();
            }
      }
   else 
      {
         _history->unpack ( in ) ;
         setValidity(true) ;
         notifyConnectedSensitiveInputs() ;
      }
}



template <typename Type>
void PsOutput<Type>::unpackAllValues (PsIncomingSynchronisationMessage & 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.
   */

   if (_validity) 
      {  
         // only in the case a suggested values was given at connection
         const Type & oldValue = _history->getPreceedingValue(0);
         _history->unpackAllValues ( in ) ;
         if(_history->getPreceedingValue(0) != oldValue) //double extract won't happen 
            {
               notifyConnectedSensitiveInputs();
            }
      }
   else 
      {
         _history->unpackAllValues ( in ) ;
         setValidity(true) ;
      }
}


template <typename Type>
inline void PsOutput<Type>::insertInStream (ostream & out) const {
   /*thread safety assessement :
     As thread safe as localInsert 
   */
   cerr<<"PsOutput<Type>::insertInStream"<<endl;
   getUsedOutput()->localInsert(out); 
}


template <typename Type>
inline void PsOutput<Type>::localInsert (ostream & out) const {
   /* thread safety assement
      thread safe : collides with set on the PsnAbstractFifo. 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) 
     {
       HeapStackTop usualContext(HeapStackTop::getSystemMemoryManager() );
       PsUnInitialisedOutputException exception(*this,"PsOutput<Type>::localInsert\n");
       exception<<"Cannot read uninitailised output of "<<_owner.getName().getCString();
       throw exception;
     }
   else 
     {
       out << *_history << " " ;
     }
}

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

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

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

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

template <typename Type>
inline void PsOutput<Type>::empty (void) {
   /* thread safety assessement : 
      as thread safe as clear of fifo. Only one simultaneous acces possible (in theory).
    */
   // MIPSPRO 7.3.1.2 workaround
   static PsSensitiveInput<Type> toto (getName(), _owner, false) ;
   _history->clear () ;
   setValidity(false) ;
}


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


template <typename Type>
inline const PsDate & PsOutput<Type>::getDateOfLastExactValue () const 
{
   touch() ;
   // this bypasses any Polator
   if (_history->getNumberOfPresentValues(1) >= 1 ) //if a value is stored
      {
         return _history->getPreceedingDate ( 0 ) ;
      }
   else 
      {
         HeapStackTop usualContext(HeapStackTop::getSystemMemoryManager() );
         PsUnInitialisedOutputException exception(*this,"PsOutput<Type>::getLastExactValue\n");
         exception<<"Impossible to get a value from an uninitialised output of "<<_owner.getName().getCString();
         throw exception;
   }
}


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


template <typename Type>
inline void PsOutput<Type>::setInPlace( const Type & newValue ) 
{

   if (_validity) 
      {
         const Type & oldValue = _history->getPreceedingValue(0);
         
         if( newValue != oldValue) //comparaison has to be done before setInPlace, because there can be a double setInPlace and we're working on references (bug corrected by D. Margery)
            {
               _history->setInPlace ( newValue, _date ) ;
               notifyConnectedSensitiveInputs();
            }
         else 
            {
               _history->setInPlace ( newValue, _date ) ;
            }          
      }
   else 
      {
         _history->setInPlace ( newValue, _date) ;
         setValidity(true) ;
         notifyConnectedSensitiveInputs();
      }   
}


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

#endif

---