SST  8.0.0
StructuralSimulationToolkit
simpleNetwork.h
1 // -*- mode: c++ -*-
2 // Copyright 2009-2018 NTESS. Under the terms
3 // of Contract DE-NA0003525 with NTESS, the U.S.
4 // Government retains certain rights in this software.
5 //
6 // Copyright (c) 2009-2018, NTESS
7 // All rights reserved.
8 //
9 // This file is part of the SST software package. For license
10 // information, see the LICENSE file in the top level directory of the
11 // distribution.
12 //
13 
14 #ifndef CORE_INTERFACES_SIMPLENETWORK_H_
15 #define CORE_INTERFACES_SIMPLENETWORK_H_
16 
17 #include <string>
18 #include <unordered_map>
19 
20 #include <sst/core/sst_types.h>
21 #include <sst/core/warnmacros.h>
22 #include <sst/core/subcomponent.h>
23 #include <sst/core/params.h>
24 
25 #include <sst/core/serialization/serializable.h>
26 
27 namespace SST {
28 
29 class Component;
30 class Event;
31 class Link;
32 
33 namespace Interfaces {
34 
35 
36 /**
37  * Generic network interface
38  */
39 class SimpleNetwork : public SubComponent {
40 
41 public:
42  /** All Addresses can be 64-bit */
43  typedef int64_t nid_t;
44 
45  static const nid_t INIT_BROADCAST_ADDR;
46 
47  /**
48  * Represents both network sends and receives
49  */
51 
52  public:
53  nid_t dest; /*!< Node ID of destination */
54  nid_t src; /*!< Node ID of source */
55  int vn; /*!< Virtual network of packet */
56  size_t size_in_bits; /*!< Size of packet in bits */
57  bool head; /*!< True if this is the head of a stream */
58  bool tail; /*!< True if this is the tail of a steram */
59 
60  private:
61  Event* payload; /*!< Payload of the request */
62 
63  public:
64 
65  /**
66  Sets the payload field for this request
67  @param payload_in Event to set as payload.
68  */
69  inline void givePayload(Event *event) {
70  payload = event;
71  }
72 
73  /**
74  Returns the payload for the request. This will also set
75  the payload to NULL, so the call will only return valid
76  data one time after each givePayload call.
77  @return Event that was set as payload of the request.
78  */
79  inline Event* takePayload() {
80  Event* ret = payload;
81  payload = NULL;
82  return ret;
83  }
84 
85  /**
86  Returns the payload for the request for inspection. This
87  call does not set the payload to NULL, so deleting the
88  request will also delete the payload. If the request is
89  going to be deleted, use takePayload instead.
90  @return Event that was set as payload of the request.
91  */
92  inline Event* inspectPayload() {
93  return payload;
94  }
95 
96  /**
97  * Trace types
98  */
99  typedef enum {
100  NONE, /*!< No tracing enabled */
101  ROUTE, /*!< Trace route information only */
102  FULL /*!< Trace all movements of packets through network */
103  } TraceType;
104 
105 
106  /** Constructor */
108  dest(0), src(0), size_in_bits(0), head(false), tail(false), payload(NULL),
109  trace(NONE), traceID(0)
110  {}
111 
113  bool head, bool tail, Event* payload = NULL) :
114  dest(dest), src(src), size_in_bits(size_in_bits), head(head), tail(tail), payload(payload),
115  trace(NONE), traceID(0)
116  {
117  }
118 
119  virtual ~Request()
120  {
121  if ( payload != NULL ) delete payload;
122  }
123 
124  inline Request* clone() {
125  Request* req = new Request(*this);
126  // Copy constructor only makes a shallow copy, need to
127  // clone the event.
128  if ( payload != NULL ) req->payload = payload->clone();
129  return req;
130  }
131 
132  void setTraceID(int id) {traceID = id;}
133  void setTraceType(TraceType type) {trace = type;}
134  int getTraceID() {return traceID;}
135  TraceType getTraceType() {return trace;}
136 
137  void serialize_order(SST::Core::Serialization::serializer &ser) override {
138  ser & dest;
139  ser & src;
140  ser & vn;
141  ser & size_in_bits;
142  ser & head;
143  ser & tail;
144  ser & payload;
145  ser & trace;
146  ser & traceID;
147  }
148 
149  protected:
150  TraceType trace;
151  int traceID;
152 
153  private:
154 
155  ImplementSerializable(SST::Interfaces::SimpleNetwork::Request)
156  };
157  /**
158  Class used to inspect network requests going through the network.
159  */
161 
162  public:
163  NetworkInspector(Component* parent) :
164  SubComponent(parent)
165  {}
166 
167  virtual ~NetworkInspector() {}
168 
169  virtual void inspectNetworkData(Request* req) = 0;
170 
171  /**
172  * The ID uniquely identifies the component in which this
173  * subcomponent is instantiated. It does not uniquely define
174  * this particular NetworkInspector, and all NetworkInspectors
175  * instantiated in the same component will get the same ID. If
176  * registering statistics, the ID is intended to be used as the
177  * subfield of the statistic.
178  */
179  virtual void initialize(std::string id) = 0;
180  };
181 
182  /** Functor classes for handling of callbacks */
183  class HandlerBase {
184  public:
185  virtual bool operator()(int) = 0;
186  virtual ~HandlerBase() {}
187  };
188 
189 
190  /** Event Handler class with user-data argument
191  * @tparam classT Type of the Object
192  * @tparam argT Type of the argument
193  */
194  template <typename classT, typename argT = void>
195  class Handler : public HandlerBase {
196  private:
197  typedef bool (classT::*PtrMember)(int, argT);
198  classT* object;
199  const PtrMember member;
200  argT data;
201 
202  public:
203  /** Constructor
204  * @param object - Pointer to Object upon which to call the handler
205  * @param member - Member function to call as the handler
206  * @param data - Additional argument to pass to handler
207  */
208  Handler( classT* const object, PtrMember member, argT data ) :
209  object(object),
210  member(member),
211  data(data)
212  {}
213 
214  bool operator()(int vn) {
215  return (object->*member)(vn,data);
216  }
217  };
218 
219  /** Event Handler class without user-data
220  * @tparam classT Type of the Object
221  */
222  template <typename classT>
223  class Handler<classT, void> : public HandlerBase {
224  private:
225  typedef bool (classT::*PtrMember)(int);
226  classT* object;
227  const PtrMember member;
228 
229  public:
230  /** Constructor
231  * @param object - Pointer to Object upon which to call the handler
232  * @param member - Member function to call as the handler
233  */
234  Handler( classT* const object, PtrMember member ) :
235  object(object),
236  member(member)
237  {}
238 
239  bool operator()(int vn) {
240  return (object->*member)(vn);
241  }
242  };
243 
244 public:
245 
246  /** Constructor, designed to be used via 'loadSubComponent'. */
248  SubComponent(comp)
249  { }
250 
251  /** Second half of building the interface.
252  Initialize network interface
253  @param portName - Name of port to connect to
254  @param link_bw - Bandwidth of the link
255  @param vns - Number of virtual networks to be provided
256  @param in_buf_size - Size of input buffers (from router)
257  @param out_buf_size - Size of output buffers (to router)
258  * @return true if the link was able to be configured.
259  */
260  virtual bool initialize(const std::string &portName, const UnitAlgebra& link_bw,
261  int vns, const UnitAlgebra& in_buf_size,
262  const UnitAlgebra& out_buf_size) = 0;
263 
264  /**
265  * Sends a network request during the init() phase
266  */
267  virtual void sendInitData(Request *req) = 0;
268 
269  /**
270  * Receive any data during the init() phase.
271  * @see SST::Link::recvInitData()
272  */
273  virtual Request* recvInitData() = 0;
274 
275  /**
276  * Sends a network request during untimed phases (init() and
277  * complete()).
278  * @see SST::Link::sendUntimedData()
279  *
280  * For now, simply call sendInitData. Once that call is
281  * deprecated and removed, this will become a pure virtual
282  * function. This means that when classes implement
283  * SimpleNetwork, they will need to overload both sendUntimedData
284  * and sendInitData with identical functionality (or having the
285  * Init version call the Untimed version) until sendInitData is
286  * removed in SST 9.0.
287  */
288  virtual void sendUntimedData(Request *req) {
289  sendInitData(req);
290  }
291 
292  /**
293  * Receive any data during untimed phases (init() and complete()).
294  * @see SST::Link::recvUntimedData()
295  *
296  * For now, simply call recvInitData. Once that call is
297  * deprecated and removed, this will become a pure virtual
298  * function. This means that when classes implement
299  * SimpleNetwork, they will need to overload both recvUntimedData
300  * and recvInitData with identical functionality (or having the
301  * Init version call the Untimed version) until recvInitData is
302  * removed in SST 9.0.
303  */
305  return recvInitData();
306  }
307 
308  // /**
309  // * Returns a handle to the underlying SST::Link
310  // */
311  // virtual Link* getLink(void) const = 0;
312 
313  /**
314  * Send a Request to the network.
315  */
316  virtual bool send(Request *req, int vn) = 0;
317 
318  /**
319  * Receive a Request from the network.
320  *
321  * Use this method for polling-based applications.
322  * Register a handler for push-based notification of responses.
323  *
324  * @param vn Virtual network to receive on
325  * @return NULL if nothing is available.
326  * @return Pointer to a Request response (that should be deleted)
327  */
328  virtual Request* recv(int vn) = 0;
329 
330  virtual void setup() override {}
331  virtual void init(unsigned int UNUSED(phase)) override {}
332  virtual void complete(unsigned int UNUSED(phase)) override {}
333  virtual void finish() override {}
334 
335  /**
336  * Checks if there is sufficient space to send on the specified
337  * virtual network
338  * @param vn Virtual network to check
339  * @param num_bits Minimum size in bits required to have space
340  * to send
341  * @return true if there is space in the output, false otherwise
342  */
343  virtual bool spaceToSend(int vn, int num_bits) = 0;
344 
345 
346  /**
347  * Checks if there is a waiting network request request pending in
348  * the specified virtual network.
349  * @param vn Virtual network to check
350  * @return true if a network request is pending in the specified
351  * virtual network, false otherwise
352  */
353  virtual bool requestToReceive( int vn ) = 0;
354 
355  /**
356  * Registers a functor which will fire when a new request is
357  * received from the network. Note, the actual request that
358  * was received is not passed into the functor, it is only a
359  * notification that something is available.
360  * @param functor Functor to call when request is received
361  */
362  virtual void setNotifyOnReceive(HandlerBase* functor) = 0;
363  /**
364  * Registers a functor which will fire when a request is
365  * sent to the network. Note, this only tells you when data
366  * is sent, it does not guarantee any specified amount of
367  * available space.
368  * @param functor Functor to call when request is sent
369  */
370  virtual void setNotifyOnSend(HandlerBase* functor) = 0;
371 
372  /**
373  * Check to see if network is initialized. If network is not
374  * initialized, then no other functions other than init() can
375  * can be called on the interface.
376  * @return true if network is initialized, false otherwise
377  */
378  virtual bool isNetworkInitialized() const = 0;
379 
380  /**
381  * Returns the endpoint ID. Cannot be called until after the
382  * network is initialized.
383  * @return Endpoint ID
384  */
385  virtual nid_t getEndpointID() const = 0;
386 
387  /**
388  * Returns the final BW of the link managed by the simpleNetwork
389  * instance. Cannot be called until after the network is
390  * initialized.
391  * @return Link bandwidth of associated link
392  */
393  virtual const UnitAlgebra& getLinkBW() const = 0;
394 
395 
396 };
397 
398 }
399 }
400 
401 #endif
virtual bool isNetworkInitialized() const =0
Check to see if network is initialized.
Definition: simpleNetwork.h:101
nid_t src
Definition: simpleNetwork.h:54
This class is basically a wrapper for objects to declare the order in which their members should be s...
Definition: serializer.h:35
Event * inspectPayload()
Returns the payload for the request for inspection.
Definition: simpleNetwork.h:92
Definition: simpleNetwork.h:102
void givePayload(Event *event)
Sets the payload field for this request.
Definition: simpleNetwork.h:69
virtual Request * recv(int vn)=0
Receive a Request from the network.
virtual bool initialize(const std::string &portName, const UnitAlgebra &link_bw, int vns, const UnitAlgebra &in_buf_size, const UnitAlgebra &out_buf_size)=0
Second half of building the interface.
virtual void sendInitData(Request *req)=0
Sends a network request during the init() phase.
Main component object for the simulation.
Definition: component.h:32
Handler(classT *const object, PtrMember member, argT data)
Constructor.
Definition: simpleNetwork.h:208
virtual Request * recvUntimedData()
Receive any data during untimed phases (init() and complete()).
Definition: simpleNetwork.h:304
virtual void sendUntimedData(Request *req)
Sends a network request during untimed phases (init() and complete()).
Definition: simpleNetwork.h:288
bool tail
Definition: simpleNetwork.h:58
virtual void setup() override
Called after all components have been constructed and initialization has completed, but before simulation time has begun.
Definition: simpleNetwork.h:330
virtual void setNotifyOnReceive(HandlerBase *functor)=0
Registers a functor which will fire when a new request is received from the network.
Request()
Constructor.
Definition: simpleNetwork.h:107
nid_t dest
Definition: simpleNetwork.h:53
virtual nid_t getEndpointID() const =0
Returns the endpoint ID.
Functor classes for handling of callbacks.
Definition: simpleNetwork.h:183
Definition: serializable.h:109
virtual Request * recvInitData()=0
Receive any data during the init() phase.
virtual void init(unsigned int UNUSED(phase)) override
Used during the init phase.
Definition: simpleNetwork.h:331
SimpleNetwork(SST::Component *comp)
Constructor, designed to be used via &#39;loadSubComponent&#39;.
Definition: simpleNetwork.h:247
Handler(classT *const object, PtrMember member)
Constructor.
Definition: simpleNetwork.h:234
Definition: simpleNetwork.h:100
Represents both network sends and receives.
Definition: simpleNetwork.h:50
virtual void finish() override
Called after simulation completes, but before objects are destroyed.
Definition: simpleNetwork.h:333
virtual bool send(Request *req, int vn)=0
Returns a handle to the underlying SST::Link.
virtual const UnitAlgebra & getLinkBW() const =0
Returns the final BW of the link managed by the simpleNetwork instance.
TraceType
Trace types.
Definition: simpleNetwork.h:99
Event Handler class with user-data argument.
Definition: simpleNetwork.h:195
bool head
Definition: simpleNetwork.h:57
virtual bool requestToReceive(int vn)=0
Checks if there is a waiting network request request pending in the specified virtual network...
virtual bool spaceToSend(int vn, int num_bits)=0
Checks if there is sufficient space to send on the specified virtual network.
size_t size_in_bits
Definition: simpleNetwork.h:56
Event * takePayload()
Returns the payload for the request.
Definition: simpleNetwork.h:79
int64_t nid_t
All Addresses can be 64-bit.
Definition: simpleNetwork.h:43
virtual void initialize(std::string id)=0
The ID uniquely identifies the component in which this subcomponent is instantiated.
Generic network interface.
Definition: simpleNetwork.h:39
Base class for Events - Items sent across links to communicate between components.
Definition: event.h:31
Performs Unit math in full precision.
Definition: unitAlgebra.h:104
virtual void setNotifyOnSend(HandlerBase *functor)=0
Registers a functor which will fire when a request is sent to the network.
Class used to inspect network requests going through the network.
Definition: simpleNetwork.h:160
virtual void complete(unsigned int UNUSED(phase)) override
Used during the init phase.
Definition: simpleNetwork.h:332
SubComponent is a class loadable through the factory which allows dynamic functionality to be added t...
Definition: subcomponent.h:29
virtual Event * clone()
Clones the event in for the case of a broadcast.
Definition: event.cc:33
int vn
Definition: simpleNetwork.h:55
Definition: serializable.h:130