torc-master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
generic/Instance.hpp
Go to the documentation of this file.
1 // Torc - Copyright 2011-2013 University of Southern California. All Rights Reserved.
2 // $HeadURL$
3 // $Id$
4 
5 // This program is free software: you can redistribute it and/or modify it under the terms of the
6 // GNU General Public License as published by the Free Software Foundation, either version 3 of the
7 // License, or (at your option) any later version.
8 //
9 // This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
10 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
11 // the GNU General Public License for more details.
12 //
13 // You should have received a copy of the GNU General Public License along with this program. If
14 // not, see <http://www.gnu.org/licenses/>.
15 
16 #ifndef TORC_GENERIC_INSTANCE_HPP
17 #define TORC_GENERIC_INSTANCE_HPP
18 
20 
21 //BOOST
22 #ifdef GENOM_SERIALIZATION
23 #include <boost/serialization/access.hpp>
24 #include <boost/serialization/split_member.hpp>
25 #include <boost/serialization/string.hpp>
26 #include <boost/serialization/map.hpp>
27 #endif //GENOM_SERIALIZATION
30 #include "torc/generic/Error.hpp"
36 #include "torc/generic/SymTab.hpp"
38 #include "torc/generic/View.hpp"
40 
41 namespace torc { namespace generic { class ObjectFactory; } }
42 namespace torc { namespace generic { class PortReference; } }
43 namespace torc { namespace generic { class RestoredInstanceUpdater; } }
44 
45 namespace torc {
46 namespace generic {
47 
48 /**
49  * @brief Represents an instantiation of a cell view in the view of another cell
50  *
51  * The Instance class is used to represent the use of a cell in another cell. EDIF supports single
52  * instances and instance arrays. The Instance acts as a base class for these the actual scalar and
53  * vector representations of instances. Parameters defined in a cell declaration can be overridden
54  * in an Instance.
55  */
56 class Instance : virtual public Composite<Instance>, public Commentable, public Nameable,
57  public PropertyContainer, public Renamable, public Visitable, public ParentedObject<View>,
58  public UserDataContainer {
59 #ifdef GENOM_SERIALIZATION
60  friend class boost::serialization::access;
61  friend class RestoredInstanceUpdater;
62 #endif //GENOM_SERIALIZATION
63 public:
64  struct MasterData {
68  std::map<std::string, ParameterSharedPtr> mParams;
69 
70  template <class Archive> void serialize(Archive& ar, unsigned int) {
71  ar & mLibrary;
72  ar & mCell;
73  ar & mView;
74  ar & mParams;
75  }
76  };
77 
78  /**
79  * Returns the context that will be used to get parameters from
80  * the parameter map. For an unbound instance,
81  * this will return an invalid value
82  */
83  virtual ParameterContext getParameterContext() const;
84 
85  /**
86  * Get the ParameterMap corresponding to this instance and it's master
87  *
88  * @return A ParameterMap consisting of only the overridden parameters.
89  */
90  virtual ParameterMapSharedPtr getParameters() const throw (Error);
91 
92  /**
93  * Get the master view for this instance.
94  *
95  * @return Master view for this instance.
96  */
97  inline ViewSharedPtr getMaster() const;
98 
99  /**
100  * Bind an instance to it's master. Instance binding consists of two steps:
101  * <ul>
102  * <li> Bind instance to cell </li>
103  * <li> Bind existing port references to ports of the cell </li>
104  * </ul>
105  * @note Instances can be bound in two states, namely, immediately, with no port reference
106  * bindings, or delayed, when all used port references are bound to master ports. There is no
107  * port binding for extern views.
108  * @param[in] inMaster Source Master view for this instance.
109  * @param[in] inMapPortReferences Whether port references are to be mapped to ports of the new
110  * master
111  * @exception Error If there is any kind of mismatch between ports etc.
112  */
113  virtual void bindToMasterView(const ViewSharedPtr& inMaster, bool inMapPortReferences = true)
114  throw (Error);
115 
116 protected:
117  void setMaster(const ViewSharedPtr& inMaster);
118 
119 public:
120  /**
121  * Add a port reference to this master. When a master is set using the set_master(), the list
122  * of port references is not created. It has to be extrinsically set.
123  *
124  * @param[in] inPortRef A port reference.
125  *
126  * @exception Error The port ref could not be added, because PortReference name is empty
127  * <ul>
128  * <li>
129  * Id : eMessageIdErrorEmptyItemName
130  * </li>
131  * <li> Context Data
132  * <ul>
133  * <li>PortReference name - <i>String</i></li>
134  * </ul>
135  * </li>
136  * </ul>
137  *
138  * @exception Error The port ref could not be added, because PortReference name is already
139  * exists
140  * <ul>
141  * <li>
142  * Id : eMessageIdErrorItemAlreadyExists
143  * </li>
144  * <li> Context Data
145  * <ul>
146  * <li>PortReference name - <i>String</i></li>
147  * </ul>
148  * </li>
149  * </ul>
150  */
151  virtual void addPortReference(const PortReferenceSharedPtr& inPortRef) throw (Error);
152 
153  /**
154  * Find a port reference.
155  *
156  * @param[in] inName String containing the name of the port.
157  */
158  virtual PortReferenceSharedPtr findPortReference(const std::string& inPortRef) throw (Error);
159 
160  /**
161  * Find a Net reference.
162  *
163  * @param[in] inName String containing the name of the Net.
164  */
165  virtual NetReferenceSharedPtr findNetReference(const std::string& inNetRef) throw (Error);
166 
167  /**
168  * Remove a given port reference.
169  *
170  * @param inName Name of the object to be delete
171  *
172  * @exception Error PortReference name is empty
173  * <ul>
174  * <li>
175  * Id : eMessageIdErrorEmptyItemName
176  * </li>
177  * <li> Context Data
178  * <ul>
179  * <li>PortReference name - <i>String</i></li>
180  * </ul>
181  * </li>
182  * </ul>
183  *
184  * @exception Error PortReference name could not be found
185  * <ul>
186  * <li>
187  * Id : eMessageIdErrorItemNotFound
188  * </li>
189  * <li> Context Data
190  * <ul>
191  * <li>PortReference name - <i>String</i></li>
192  * </ul>
193  * </li>
194  * </ul>
195  *
196  */
197  virtual void removePortReference(const std::string& inName) throw (Error);
198 
199  /**
200  * Get list of all port references.
201  *
202  * @return List of port references
203  */
204  virtual void getPortReferences(std::vector<PortReferenceSharedPtr>&) const;
205 
206  /**
207  * Set list of all port references.
208  *
209  * @param[in] inSource List of port references
210  */
211  virtual void setPortReferences(const std::vector<PortReferenceSharedPtr>& inSource)
212  throw (Error);
213 
214  /**
215  * Apply action on all PortReferences.
216  * @param[in] action Action to be applied
217  *
218  */
219  template <typename _Action> inline void applyOnAllPortReferences(const _Action& action)
220  throw (Error);
221 
222  /**
223  * Get the designated number.
224  *
225  * @return std::string Value representing designated number of a view interface.
226  */
227  inline const std::string getDesignator() const;
228 
229  /**
230  * Set the designated number.
231  *
232  * @param[in] inSource std::string representing designated number of a view interface.
233  */
234  void setDesignator(const std::string& inSource);
235 
236  /**
237  * Get the pointer to the timing object
238  *
239  * @return Pointer to the timing object
240  */
241  inline const TimingSharedPtr getTiming() const;
242 
243  /**
244  * Set the pointer to the timing object
245  *
246  * @param[in] inSource Pointer to the timing object
247  */
248  void setTiming(const TimingSharedPtr& inSource);
249 
250  Instance();
251 
252  virtual ~Instance() throw ();
253 
254 private:
255  Instance(const Instance& source);
256  Instance& operator=(const Instance& source);
257 
258 private:
259 #ifdef GENOM_SERIALIZATION
260  template <class Archive> void load(Archive& ar, unsigned int);
261 
262  template <class Archive> void save(Archive& ar, unsigned int) const;
263 
264  BOOST_SERIALIZATION_SPLIT_MEMBER()
265 
266  void restoreMaster() throw(Error);
267 
268  mutable MasterData *mMasterData;
269 #endif //GENOM_SERIALIZATION
276 };
277 
278 /**
279  * Get the master view for this instance.
280  *
281  * @return Master view for this instance.
282  */
284  return mMaster;
285 }
286 
287 /**
288  * Apply action on all PortReferences.
289  * @param[in] action Action to be applied
290  *
291  */
292 template <typename _Action> inline void Instance::applyOnAllPortReferences(const _Action& action)
293  throw (Error) {
294  try {
295  mPortReferences.applyOnAll(action);
296  } catch(Error& e) {
297  e.setCurrentLocation(__FUNCTION__, __FILE__, __LINE__);
298  throw;
299  }
300 }
301 
302 inline const std::string Instance::getDesignator() const {
303  return mDesignator;
304 }
305 
306 /**
307  * Get the pointer to the timing object
308  *
309  * @return Pointer to the timing object
310  */
311 inline const TimingSharedPtr Instance::getTiming() const {
312  return mTiming;
313 }
314 
315 } // namespace generic
316 } // namespace torc
317 
318 #endif // TORC_GENERIC_INSTANCE_HPP
Represents an instantiation of a cell view in the view of another cell.
An object that has a parent.
virtual void getPortReferences(std::vector< PortReferenceSharedPtr > &) const
void applyOnAllPortReferences(const _Action &action)
Represents objects that have properties.
Interface for objects that can be composed within each other.
Definition: Composite.hpp:45
virtual void bindToMasterView(const ViewSharedPtr &inMaster, bool inMapPortReferences=true)
virtual ParameterContext getParameterContext() const
void serialize(Archive &ar, unsigned int)
Represents all classes that can hold user comments.
Definition: Commentable.hpp:36
Represents class that can hold userData.
SymTab< std::string, PortReferenceSharedPtr > mPortReferences
std::string string
boost::shared_ptr< NetReference > NetReferenceSharedPtr
void setMaster(const ViewSharedPtr &inMaster)
The Error object thrown by different methods of EdifOM.
Definition: Error.hpp:41
virtual void removePortReference(const std::string &inName)
boost::shared_ptr< PortReference > PortReferenceSharedPtr
virtual ParameterMapSharedPtr getParameters() const
void setDesignator(const std::string &inSource)
ViewSharedPtr getMaster() const
const std::string getDesignator() const
void setTiming(const TimingSharedPtr &inSource)
const TimingSharedPtr getTiming() const
virtual NetReferenceSharedPtr findNetReference(const std::string &inNetRef)
boost::shared_ptr< View > ViewSharedPtr
An object that has a name.
Definition: Nameable.hpp:34
virtual PortReferenceSharedPtr findPortReference(const std::string &inPortRef)
std::map< std::string, ParameterSharedPtr > mParams
Represents objects that can be renamed.
virtual void setPortReferences(const std::vector< PortReferenceSharedPtr > &inSource)
SymTab< std::string, NetReferenceSharedPtr > mNetReferences
boost::shared_ptr< Timing > TimingSharedPtr
virtual void addPortReference(const PortReferenceSharedPtr &inPortRef)
boost::shared_ptr< ParameterMap > ParameterMapSharedPtr
An object that receives an inoutVisitor.
Definition: Visitable.hpp:38
void setCurrentLocation(const std::string &inFunction, const std::string &inFile, uint32_t inLine)
Definition: Error.cpp:73