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. Input readings are
00033  * combined in a union fashion over all participating devices,
00034  * output 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 configured to have individual
00040  * outputs or inputs, 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 common condition variable. 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 
00051 FAUDES_TYPE_DECLARATION(DeviceContainer,xDevice,vDevice)
00052 
00053 
00054  public:
00055 
00056 
00057   /** Iterator for const access to individual devices*/
00058   typedef std::vector<vDevice*>::const_iterator Iterator;
00059 
00060 
00061   /**
00062    * Default constructor
00063    */
00064   xDevice(void);
00065 
00066   /**
00067    * Construct on heap from token reader.
00068    *
00069    * This constructor examines the token strean, determines the coressponding
00070    * class and constructs the device on the heap. Todo: the implementation
00071    * of this function is a hack, there must be proper
00072    * solution to this issue.
00073    *
00074    * @param rTr
00075    *   TokenReader to read from
00076    * @return
00077    *  vDevice pointer
00078    *
00079    * @exception Exception
00080    *   - token mismatch (id 552)
00081    *   - IO errors (id 1)
00082    */
00083   static xDevice* FromTokenReader(TokenReader& rTr);
00084 
00085   /**
00086    * Construct on heap from file.
00087    *
00088    * This constructor examines the file, determines the coressponding
00089    * class and constructs the device on the heap.
00090    *
00091    * @param rFileName
00092    *   Filename
00093    * @return
00094    *  vDevice pointer
00095    *
00096    * @exception Exception
00097    *   - token mismatch (id 552)
00098    *   - IO errors (id 1)
00099    */
00100   static xDevice* FromFile(const std::string& rFileName);
00101 
00102   /**
00103    * Explicit destructor.
00104    */
00105   virtual ~xDevice(void);
00106 
00107 
00108   /**
00109    * Set Iterator to first device
00110    *
00111    * @return
00112    *   Iterator to first device
00113    */
00114   Iterator Begin(void) const { return mDevices.begin() ; };
00115 
00116   /**
00117    * Set Iterator to last device
00118    *
00119    * @return
00120    *   Iterator to last device
00121    */
00122   Iterator End(void) const { return mDevices.end() ; };
00123 
00124   /**
00125    *
00126    * Get number of devices
00127    */
00128   Idx Size(void) const { return mDevices.size(); };
00129 
00130 
00131   /**
00132    *  Insert a new device.
00133    *  An xDevice is configured by inserting vDevices. An xDevice cannot be
00134    *  configured by individual output/sensro events.
00135    *
00136    *  Note: by inserting a device into an xdevice its ownership
00137    *  will be assumed by the xdevice and therewith the right to destoy
00138    *  it.
00139    *
00140    *  @param device
00141    *    Pointer to vDevice
00142    */
00143   void Insert(vDevice* device);
00144   
00145   /**
00146    * Insert a new device by Filename
00147    *
00148    * An xDevice is configured by inserting vDevices. An xDevice cannot be
00149    * configured by individual output/sensro events.
00150    *
00151    * Note: by inserting a device into an xdevice its ownership
00152    * will be assumed by the xdevice and therewith the right to destoy
00153    * 
00154    * For information on how to write such a file see the "iodevice" - tutorial
00155    *
00156    * @param rFileName
00157    *   Configuration-file to build up device
00158    */
00159  
00160   void Insert(const std::string& rFileName);
00161 
00162   
00163 
00164   /** 
00165    * Dummy. An xDevice does not provide event based configuration. Use Insert instead. This function
00166    * will throw an execption
00167    */
00168   void Configure(Idx event, const AttributeDeviceEvent& attr);
00169 
00170   /** 
00171    * An xDevice does not provide event based configuration. Use Insert instead. 
00172    * This function will throw an execption
00173    */
00174   void Configure(const EventSet& rEvents);
00175 
00176    /**
00177     *
00178     *  Build up internal data structures. I.e. (event-idx,int) - map
00179     */
00180   void Compile(void) ;
00181 
00182 
00183   /**
00184    * Clear all configuarations and destroy existing devices
00185    *
00186    */
00187   void Clear(void);
00188 
00189 
00190   /** reset all dynamic state, i.e. call reset on each device */
00191   void Reset(void);
00192 
00193   /** Test for reset request */
00194   bool ResetRequest(void);
00195 
00196   /**
00197    * Activate the devices. This function enables output execution and input reading.
00198    *
00199    * @exception Exception
00200    *   - Not yet configured (id 551)
00201    */
00202   void Start(void);
00203 
00204   /**
00205    * Deactivate the device. This function disables output execution and input reading.
00206    *
00207    */
00208   void Stop(void);
00209 
00210   /**
00211    * Get status. This function returns the current status of the device.
00212    * In derived classes that use background threads for input reading etc,
00213    * a device may change its status without notice. Dont forget to reimplement
00214    * this method with an appropriate mutex.
00215    *
00216    */
00217   DeviceState Status(void);
00218 
00219   /**
00220    * Run output command on relevant device.
00221    *
00222    * @exception Exception
00223    *   - unknown output event (id 65)
00224    *
00225    */
00226   void WriteOutput(Idx output);
00227 
00228   /**
00229    * Flush any pending IO Operations.
00230    *
00231    * Pass on flush output buffers to participating devices.
00232    *
00233    */
00234   virtual void FlushOutputs(void);
00235 
00236 
00237   /**
00238    * Report global fauDES-time
00239    * Note: per convention we take the time of the first
00240    * device inserted in xDevice as global time
00241    *
00242    * @return
00243    *   fauDES-time
00244    */
00245   tpTime::Type CurrentTime(void);
00246 
00247   /**
00248    * Report global fauDES-time
00249    * Note: per convention we take the time of the first
00250    * device inserted in xDevice as global time
00251    *
00252    * @return
00253    *   fauDES-time
00254    */
00255   long int CurrentTimeMs(void);
00256 
00257   /**
00258    * Set physical time in ftu.
00259    *
00260    * @param now
00261    *   now in faudes time units (ftu).
00262    */
00263   virtual void CurrentTime(tpTime::Type now);
00264 
00265   /**
00266    * Set physical time in ms.
00267    *
00268    * @param nowms
00269    *   now in msec
00270    */
00271   virtual void CurrentTimeMs(long int nowms);
00272 
00273 
00274 
00275 protected:
00276 
00277   // internal iterator type
00278   typedef std::vector<vDevice*>::iterator iterator;
00279 
00280 
00281   /**
00282    * Actual method to read device configuration from tokenreader.
00283    *
00284    * DoRead basically calls the DoWrite-function of all devices which are part of xDevice
00285    *
00286    * @param rTr
00287    *   TokenReader to read from
00288    * @param rLabel
00289    *   Section to read
00290    * @param pContext
00291    *   Read context to provide contextual information
00292    *
00293    * @exception Exception
00294    *   - IO error (id 1)
00295    */
00296   virtual void DoReadConfiguration(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00297 
00298   /**
00299    * Write the device patrameters to a TokenWriter.
00300    *
00301    *
00302    * @param rTw
00303    *   Reference to TokenWriter
00304    * @param rLabel
00305    *   Label of section to write
00306    * @param pContext
00307    *   Read context to provide contextual information
00308    * @exception Exception
00309    *   - IO errors (id 2)
00310    */
00311   virtual void DoWriteConfiguration(TokenWriter& rTw, const std::string& rLabel="", const Type* pContext=0) const;
00312 
00313   /** Return first Device */
00314   iterator Begin(void) { return mDevices.begin() ; };
00315 
00316   /** Return last Device */
00317   iterator End(void) { return mDevices.end() ; };
00318 
00319   /** Vector of member-devices */
00320   std::vector<vDevice*> mDevices;
00321 
00322   /** Vector of member-device-names*/
00323   std::vector<std::string> mDeviceNames;
00324 
00325   /** Compiled data: Input map to map input idx to device no */
00326   std::map<Idx,int> mInputToDevice;
00327 
00328   /** Compiled data: Output Map to map input idx to device no */
00329   std::map<Idx,int> mOutputToDevice;
00330 
00331   /** Current device state: remember last stop/down command */
00332   bool lastCommandWasStart;
00333 
00334 
00335 };
00336 
00337 
00338 
00339 } 
00340 
00341 
00342 #endif
00343 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen