SST  11.0.0
StructuralSimulationToolkit
link.h
1 // Copyright 2009-2021 NTESS. Under the terms
2 // of Contract DE-NA0003525 with NTESS, the U.S.
3 // Government retains certain rights in this software.
4 //
5 // Copyright (c) 2009-2021, NTESS
6 // All rights reserved.
7 //
8 // This file is part of the SST software package. For license
9 // information, see the LICENSE file in the top level directory of the
10 // distribution.
11 
12 #ifndef SST_CORE_LINK_H
13 #define SST_CORE_LINK_H
14 
15 #include "sst/core/sst_types.h"
16 
17 #include "sst/core/event.h"
18 
19 namespace SST {
20 
21 #define _LINK_DBG( fmt, args...) __DBG( DBG_LINK, Link, fmt, ## args )
22 
23 class TimeConverter;
24 class LinkPair;
25 class Simulation_impl;
26 class ActivityQueue;
27 // class SyncBase;
28 
29 class UnitAlgebra;
30 
31  /** Link between two components. Carries events */
32 class Link {
33  typedef enum { POLL, HANDLER, QUEUE } Type_t;
34 public:
35 
36  friend class LinkPair;
37  friend class RankSync;
38  friend class ThreadSync;
39  friend class Simulation_impl;
40  // friend class SyncBase;
41  friend class SyncManager;
42  friend class ComponentInfo;
43 
44  /** Create a new link with a given ID */
45 #if !SST_BUILDING_CORE
46  Link(LinkId_t id) __attribute__ ((deprecated("this function was not intended to be used outside of SST core and will be removed in SST 12.")));
47 #else
48  Link(LinkId_t id);
49 #endif
50 
51  virtual ~Link();
52 
53  /** Set additional Latency to be added to events being sent out of this link
54  * @param cycles Number of Cycles to be added
55  * @param timebase Base Units of cycles
56  */
57  void addSendLatency(int cycles, const std::string& timebase);
58 
59  /** Set additional Latency to be added to events being sent out of this link
60  * @param cycles Number of Cycles to be added
61  * @param timebase Base Units of cycles
62  */
63  void addSendLatency(SimTime_t cycles, TimeConverter* timebase);
64 
65  /** Set additional Latency to be added on to events coming in on this link.
66  * @param cycles Number of Cycles to be added
67  * @param timebase Base Units of cycles
68  */
69  void addRecvLatency(int cycles, const std::string& timebase);
70 
71  /** Set additional Latency to be added on to events coming in on this link.
72  * @param cycles Number of Cycles to be added
73  * @param timebase Base Units of cycles
74  */
75  void addRecvLatency(SimTime_t cycles, TimeConverter* timebase);
76 
77  /** Set the callback function to be called when a message is
78  * delivered. Not available for Polling links.
79  * @param functor Functor to call when message is delivered
80  */
81  void setFunctor(Event::HandlerBase* functor);
82 
83  /** Replace the callback function to be called when a message is
84  * delivered. Any previous handler will be deleted.
85  * Not available for Polling links.
86  * @param functor Functor to call when message is delivered
87  */
88  void replaceFunctor(Event::HandlerBase* functor);
89 
90  /** Specifies that this link has no callback, and is poll-based only */
91 #if !SST_BUILDING_CORE
92  void setPolling() __attribute__ ((deprecated("this function was not intended to be used outside of SST core and will be removed in SST 12.")));
93 #else
94  void setPolling();
95 #endif
96 
97  /** Send an event over the link with additional delay. Sends an event
98  * over a link with an additional delay specified with a
99  * TimeConverter. I.e. the total delay is the link's delay + the
100  * additional specified delay.
101  * @param delay - additional delay
102  * @param tc - time converter to specify units for the additional delay
103  * @param event - the Event to send
104  */
105  void send( SimTime_t delay, TimeConverter* tc, Event* event );
106 
107  /** Send an event with additional delay. Sends an event over a link
108  * with additional delay specified by the Link's default
109  * timebase.
110  * @param delay The additional delay, in units of the default Link timebase
111  * @param event The event to send
112  */
113  inline void send( SimTime_t delay, Event* event ) {
114  send(delay,defaultTimeBase,event);
115  }
116 
117  /** Send an event with the Link's default delay
118  * @param event The event to send
119  */
120  inline void send( Event* event ) {
121  send( 0, event );
122  }
123 
124 
125  /** Retrieve a pending event from the Link. For links which do not
126  * have a set event handler, they can be polled with this function.
127  * Returns nullptr if there is no pending event.
128  * Not available for HANDLER-type links.
129  * @return Event if one is available
130  * @return nullptr if no Event is available
131  */
132  Event* recv();
133 
134 
135  /** Manually set the default detaulTimeBase
136  * @param tc TimeConverter object for the timebase
137  */
139 
140  /** Return the default Time Base for this link
141  * @return the default Time Base for this link
142  */
144 
145  /** Return the default Time Base for this link
146  * @return the default Time Base for this link
147  */
148  const TimeConverter* getDefaultTimeBase() const;
149 
150  /** Causes an event to be delivered to the registered callback */
151 #if !SST_BUILDING_CORE
152  inline void deliverEvent(Event* event) const __attribute__ ((deprecated("this function was not intended to be used outside of SST core and will be removed in SST 12."))) {
153 #else
154  inline void deliverEvent(Event* event) const {
155 #endif
156  (*rFunctor)(event);
157  }
158 
159  /** Return the ID of this link
160  * @return the unique ID for this link
161  */
162  LinkId_t getId() { return id; }
163 
164  /** Send data during the init() or complete() phase.
165  * @param data event to send
166  */
167  void sendUntimedData(Event* data);
168 
169  /** Receive an event (if any) during the init() or complete() phase.
170  * @return Event if one is available
171  * @return nullptr if no Event is available
172  */
174 
175  /** Send data during the init() or complete() phase.
176  * Same as sendUntimedData()
177  * @param init_data data to send
178  */
179  void sendInitData(Event* init_data) {
180  sendUntimedData(init_data);
181  }
182 
183  /** Receive an event (if any) during the init() or complete() phase.
184  * Same as recvUntimedData()
185  * @return Event if one is available
186  * @return nullptr if no Event is available
187  */
189  return recvUntimedData();
190  }
191 
192 #if !SST_BUILDING_CORE
193  void setAsConfigured() __attribute__ ((deprecated("this function was not intended to be used outside of SST core and will be removed in SST 12."))) {
194 #else
195  void setAsConfigured() {
196 #endif
197  configured = true;
198  }
199 
200  /** Return whether link has been configured
201  * @return whether link is configured
202  */
203  bool isConfigured() {
204  return configured;
205  }
206 
207 #ifdef __SST_DEBUG_EVENT_TRACKING__
208  void setSendingComponentInfo(const std::string& comp_in, const std::string& type_in, const std::string& port_in) {
209  comp = comp_in;
210  ctype = type_in;
211  port = port_in;
212  }
213 
214  const std::string& getSendingComponentName() { return comp; }
215  const std::string& getSendingComponentType() { return ctype; }
216  const std::string& getSendingPort() { return port; }
217 
218 #endif
219 
220 protected:
221  Link();
222 
223  /** Queue of events to be received by the owning component */
225  /** Queue of events to be received during init by the owning component */
227  /** Currently active Queue */
229  /** Uninitialized queue. Used for error detection */
231  /** Uninitialized queue. Used for error detection */
233  /** Uninitialized queue. Used for error detection */
235 
236  /** Receive functor. This functor is set when the link is connected.
237  Determines what the receiver wants to be called
238  */
240 
241  /** Timebase used if no other timebase is specified. Used to specify
242  the units for added delays when sending, such as in
243  Link::send(). Often set by the Component::registerClock()
244  function if the regAll argument is true.
245  */
247 
248  /** Latency of the link. It is used by the partitioner as the
249  weight. This latency is added to the delay put on the event by
250  the component.
251  */
252  SimTime_t latency;
253 
254  /** Pointer to the opposite side of this link */
256 
257 private:
258  Link( const Link& l );
259 
260  /** Set minimum link latency */
261  void setLatency(Cycle_t lat);
262 
263  void sendUntimedData_sync(Event* data);
264  void finalizeConfiguration();
265  void prepareForComplete();
266 
267  Type_t type;
268  LinkId_t id;
269  bool configured;
270 
271 #ifdef __SST_DEBUG_EVENT_TRACKING__
272  std::string comp;
273  std::string ctype;
274  std::string port;
275 #endif
276 
277 };
278 
279 /** Self Links are links from a component to itself */
280 class SelfLink : public Link {
281 public:
282  SelfLink() : Link()
283  {
284  pair_link = this;
285  latency = 0;
286  }
287 
288 };
289 
290 
291 } // namespace SST
292 
293 #endif // SST_CORE_LINK_H
Definition: syncManager.h:113
A class to convert between a component's view of time and the core's view of time.
Definition: timeConverter.h:25
Definition: syncManager.h:33
Definition: syncManager.h:73
Main control class for a SST Simulation.
Definition: simulation_impl.h:72
Defines a pair of links (to define a connected link)
Definition: linkPair.h:24
Functor classes for Event handling.
Definition: event.h:102
Definition: componentInfo.h:40
Base Class for a queue of Activities.
Definition: activityQueue.h:22
Base class for Events - Items sent across links to communicate between components.
Definition: event.h:31