libFAUDES

Sections

Index

iop_xdevice.h

Go to the documentation of this file.
00001 /** @file iop_xdevice.h Virtual device for interface definition  */
00002 
00003 /*
00004    FAU Discrete Event Systems Library (libfaudes)
00005 
00006    Copyright (C) 2008, Thomas Moor
00007    Exclusive copyright is granted to Klaus Schmidt
00008 
00009 */
00010 
00011 
00012 
00013 #ifndef FAUDES_XDEVICE_H
00014 #define FAUDES_XDEVICE_H
00015 
00016 #include "corefaudes.h"
00017 #include "tp_include.h"
00018 #include "iop_vdevice.h"
00019 
00020 
00021 
00022 
00023 
00024 namespace faudes {
00025 
00026 
00027 
00028 
00029 /**
00030  * Container of devices.
00031  *
00032  * The xDevices is a container of vDevices. Sensor readings are
00033  * combined in a union fashion over all participating devices,
00034  * actuator writings are dispatched to the relevant device. Formally,
00035  * the xDevice class is derived from the vDevice class to provide the
00036  * same interaface to a simulator. Ie, the application does not
00037  * need to know whether is acts on a single vDevice or an xDevice. This
00038  * is also true for configuration from file, but of cause not for programatical
00039  * configuration. An xDevice may not be configureb to have individual
00040  * actuators or sensors, but to hold particular vDevices.
00041  *
00042  * Technical detail: the xDevice uses the vDevice interface to register a
00043  * common event fifo buffer and a pthread condition. Thus, the xDevice only works
00044  * with devices that support this configuration feature.
00045  *
00046  * @ingroup IODevicePlugin
00047  */
00048 
00049 class xDevice : public vDevice {
00050  public:
00051 
00052   // Note write-permision
00053 
00054   /** Iterator for const access to individual devices*/
00055   typedef std::vector<vDevice*>::const_iterator Iterator;
00056 
00057 
00058   /**
00059    * Default constructor
00060    */
00061   xDevice(void);
00062 
00063   /**
00064    * Construct on heap from token reader.
00065    *
00066    * This constructor examines the token strean, determines the coressponding
00067    * class and constructs the device on the heap. Todo: the implementation
00068    * of this function is a hack, there must be proper
00069    * solution to this issue.
00070    *
00071    * @param rTr
00072    *   TokenReader to read from
00073    * @return
00074    *  vDevice pointer
00075    *
00076    * @exception Exception
00077    *   - token mismatch (id 552)
00078    *   - IO errors (id 1)
00079    */
00080   static xDevice* FromTokenReader(TokenReader& rTr);
00081 
00082   /**
00083    * Construct on heap from file.
00084    *
00085    * This constructor examines the file, determines the coressponding
00086    * class and constructs the device on the heap.
00087    *
00088    * @param rFileName
00089    *   Filename
00090    * @return
00091    *  vDevice pointer
00092    *
00093    * @exception Exception
00094    *   - token mismatch (id 552)
00095    *   - IO errors (id 1)
00096    */
00097   static xDevice* FromFile(const std::string& rFileName);
00098 
00099   /**
00100    * Explicit destructor.
00101    */
00102   virtual ~xDevice(void);
00103 
00104 
00105   /**
00106    * Set Iterator to first device
00107    *
00108    * @return
00109    *   Iterator to first device
00110    */
00111   Iterator Begin(void) const { return mDevices.begin() ; };
00112 
00113   /**
00114    * Set Iterator to last device
00115    *
00116    * @return
00117    *   Iterator to last device
00118    */
00119   Iterator End(void) const { return mDevices.end() ; };
00120 
00121   /**
00122    *
00123    * Get number of devices
00124    */
00125   Idx Size(void) const { return mDevices.size(); };
00126 
00127 
00128   /**
00129    *  Insert a new device.
00130    *  An xDevice is configured by inserting vDevices. An xDevice cannot be
00131    *  configured by individual actuator/sensro events.
00132    *
00133    *  Note: by inserting a device into an xdevice its ownership
00134    *  will be assumed by the xdevice and therewith the right to destoy
00135    *  it.
00136    *
00137    *  @param device
00138    *    Pointer to vDevice
00139    */
00140   void Insert(vDevice* device);
00141   
00142   /**
00143    * Insert a new device by Filename
00144    *
00145    * An xDevice is configured by inserting vDevices. An xDevice cannot be
00146    * configured by individual actuator/sensro events.
00147    *
00148    * Note: by inserting a device into an xdevice its ownership
00149    * will be assumed by the xdevice and therewith the right to destoy
00150    * 
00151    * For information on how to write such a file see the "iodevice" - tutorial
00152    *
00153    * @param rFileName
00154    *   Configuration-file to build up device
00155    */
00156  
00157   void Insert(const std::string& rFileName);
00158 
00159   
00160 
00161   /** 
00162    * Dummy. An xDevice does not provide event based configuration. Use Insert instead. This function
00163    * will throw an execption
00164    */
00165   void Configure(Idx event, const AttributeDeviceEvent& attr);
00166 
00167   /** 
00168    * Dummy. An xDevice does not provide event based configuration. Use Insert instead. This function
00169    * will throw an execption
00170    */
00171   void Configure(const EventSet& rEvents);
00172 
00173    /**
00174     *
00175     *  Build up internal data structures. I.e. (event-idx,int) - map
00176     */
00177   void Compile(void) ;
00178 
00179 
00180   /**
00181    * Clear all configuarations and destroy existing devices
00182    *
00183    */
00184   void Clear(void);
00185 
00186 
00187   /** reset all dynamic state, iw call reset on each device */
00188   void Reset(void);
00189 
00190 
00191   /**
00192    * Activate the devices. xxx This function enables actuator execution and sensor reading.
00193    *
00194    * @exception Exception
00195    *   - Not yet configured (id 551)
00196    */
00197   void Start(void);
00198 
00199   /**
00200    * Deactivate the device. This function disables actuator execution and sensor reading.
00201    *
00202    */
00203   void Stop(void);
00204 
00205   /**
00206    * Get status. This function returns the current status of the device.
00207    * In derived classes that use background threads for sensor reading etc,
00208    * a device may change its status without notice. Dont forget to reimplement
00209    * this method with an appropriate mutex.
00210    *
00211    */
00212   DeviceState Status(void);
00213 
00214   /**
00215    * Run actuator command.
00216    *
00217    * @exception Exception
00218    *   - unknown actuator event (id 65)
00219    *
00220    */
00221   void WriteActuator(Idx actuator);
00222 
00223   /**
00224    * Report global fauDES-time
00225    * Note: per convention we take the time of the first
00226    * device inserted in xDevice as global time
00227    *
00228    * @return
00229    *   fauDES-time
00230    */
00231   tpTime::Type CurrentTime(void);
00232 
00233 
00234   /**
00235    * Report global fauDES-time
00236    * Note: per convention we take the time of the first
00237    * device inserted in xDevice as global time
00238    *
00239    * @return
00240    *   fauDES-time
00241    */
00242   long int CurrentTimeMs(void);
00243 
00244 
00245   /**
00246    * Set physical time in ftu.
00247    *
00248    * @param now
00249    *   now in faudes time units (ftu).
00250    */
00251   virtual void CurrentTime(tpTime::Type now);
00252 
00253 
00254   /**
00255    * Set physical time in ms.
00256    *
00257    * @param nowms
00258    *   now in msec
00259    */
00260   virtual void CurrentTimeMs(long int nowms);
00261 
00262 
00263 
00264 protected:
00265 
00266   //Notice: not const -> write-perimision
00267   typedef std::vector<vDevice*>::iterator iterator;
00268 
00269 
00270   /**
00271    * Actual method to read device configuration from tokenreader.
00272    *
00273    * DoRead basically calls the DoWrite-function of all devices which are part of xDevice
00274    *
00275    * @param rTr
00276    *   TokenReader to read from
00277    * @param rLabel
00278    *   Section to read
00279    * @param pContext
00280    *   Read context to provide contextual information
00281    *
00282    * @exception Exception
00283    *   - IO error (id 1)
00284    */
00285   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00286 
00287   /**
00288    * Actual method to write the device configuration to a TokenWriter.
00289    *
00290    * DoWrite basically calls the DoWrite-function of all devices which are part of xDevice
00291    *
00292    * @param rTw
00293    *   Reference to TokenWriter
00294    * @param rLabel
00295    *   Label of section to write
00296    * @param pContext
00297    *   Read context to provide contextual information
00298    * @exception Exception
00299    *   - IO errors (id 2)
00300    */
00301   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="", const Type* pContext=0) const;
00302 
00303   /** Return first Device */
00304   iterator Begin(void) { return mDevices.begin() ; };
00305 
00306   /** Return last Device */
00307   iterator End(void) { return mDevices.end() ; };
00308 
00309   /** Vector of member-devices */
00310   std::vector<vDevice*> mDevices;
00311 
00312   /** Vector of member-device-names*/
00313   std::vector<std::string> mDeviceNames;
00314 
00315   /** Compiled data: Sensor map to map sensor idx to device no */
00316   std::map<Idx,int> mSensorToDevice;
00317 
00318   /** Compiled data: Actuator Map to map sensor idx to device no */
00319   std::map<Idx,int> mActuatorToDevice;
00320 
00321   /** Current device state: remember last stop/down command */
00322   bool lastCommandWasStart;
00323 
00324 
00325 };
00326 
00327 
00328 
00329 } 
00330 
00331 
00332 #endif
00333 

libFAUDES 2.14g --- 2009-12-3 --- c++ source docu by doxygen 1.5.6