Add missing lifecycle functions

Improve comments Update copyright dates
sstsimulator · May 13, 2024 · d305912 · d305912
1 parent 9aa9de4
commit d305912
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 49 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright 2009-2023 National Technology and Engineering Solutions of Sandia,
+Copyright 2009-2024 National Technology and Engineering Solutions of Sandia,
 LLC (NTESS).  Under the terms of Contract DE-NA-0003525, the U.S. Government
 retains certain rights in this software.
 
@@ -7,7 +7,7 @@ by National Technology and Engineering Solutions of Sandia, LLC., a wholly
 owned subsidiary of Honeywell International, Inc., for the U.S. Department of
 Energy's National Nuclear Security Administration under contract DE-NA0003525.
 
-Copyright (c) 2009-2023, NTESS
+Copyright (c) 2009-2024, NTESS
 
 All rights reserved.
 

diff --git a/src/simpleExternalElement.cc b/src/simpleExternalElement.cc
@@ -1,64 +1,73 @@
-// Copyright 2009-2023 NTESS. Under the terms
+// Copyright 2009-2024 NTESS. Under the terms
 // of Contract DE-NA0003525 with NTESS, the U.S.
 // Government retains certain rights in this software.
 //
-// Copyright (c) 2009-2023, NTESS
+// Copyright (c) 2009-2024, NTESS
 // All rights reserved.
 //
 // This file is part of the SST software package. For license
 // information, see the LICENSE file in the top level directory of the
 // distribution.
 
-#include <sst/core/sst_config.h>
+#include <sst/core/sst_config.h> // This include is REQUIRED for all implementation files
+
 #include "simpleExternalElement.h"
 
 SimpleExternalElement::SimpleExternalElement( SST::ComponentId_t id, SST::Params& params ) :
-	SST::Component(id), repeats(0) {
+    SST::Component(id), repeats(0) {
 
-	output.init("SimpleExternalElement-" + getName() + "-> ", 1, 0, SST::Output::STDOUT);
+    output.init("SimpleExternalElement-" + getName() + "-> ", 1, 0, SST::Output::STDOUT);
 
-	printFreq  = params.find<SST::Cycle_t>("printFrequency", 5);
-	maxRepeats = params.find<SST::Cycle_t>("repeats", 10);
+    printFreq  = params.find<SST::Cycle_t>("printFrequency", 5);
+    maxRepeats = params.find<SST::Cycle_t>("repeats", 10);
 
-	if( ! (printFreq > 0) ) {
-		output.fatal(CALL_INFO, -1, "Error: printFrequency must be greater than zero.\n");
-	}
+    if( ! (printFreq > 0) ) {
+    	output.fatal(CALL_INFO, -1, "Error: printFrequency must be greater than zero.\n");
+    }
 
-	output.verbose(CALL_INFO, 1, 0, "Config: maxRepeats=%" PRIu64 ", printFreq=%" PRIu64 "\n",
-		static_cast<uint64_t>(maxRepeats), static_cast<uint64_t>(printFreq));
+    output.verbose(CALL_INFO, 1, 0, "Config: maxRepeats=%" PRIu64 ", printFreq=%" PRIu64 "\n",
+        static_cast<uint64_t>(maxRepeats), static_cast<uint64_t>(printFreq));
 
-	// Just register a plain clock for this simple example
-    	registerClock("100MHz", new SST::Clock::Handler<SimpleExternalElement>(this, &SimpleExternalElement::clockTick));
+    // Just register a plain clock for this simple example
+    registerClock("100MHz", new SST::Clock::Handler<SimpleExternalElement>(this, &SimpleExternalElement::clockTick));
 
-	// Tell SST to wait until we authorize it to exit
-    	registerAsPrimaryComponent();
-    	primaryComponentDoNotEndSim();
+    // Tell SST to wait until we authorize it to exit
+    registerAsPrimaryComponent();
+    primaryComponentDoNotEndSim();
 }
 
-SimpleExternalElement::~SimpleExternalElement() {
 
+SimpleExternalElement::~SimpleExternalElement() { }
+
+void SimpleExternalElement::init(unsigned int phase) {
+    output.verbose(CALL_INFO, 1, 0, "Component is participating in phase %d of init.\n", phase);
 }
 
 void SimpleExternalElement::setup() {
-	output.verbose(CALL_INFO, 1, 0, "Component is being setup.\n");
+    output.verbose(CALL_INFO, 1, 0, "Component is being setup.\n");
+}
+
+void SimpleExternalElement::complete(unsigned int phase) {
+    output.verbose(CALL_INFO, 1, 0, "Component is participating in phase %d of complete.\n", phase);
 }
 
 void SimpleExternalElement::finish() {
-	output.verbose(CALL_INFO, 1, 0, "Component is being finished.\n");
+    output.verbose(CALL_INFO, 1, 0, "Component is being finished.\n");
 }
 
+
 bool SimpleExternalElement::clockTick( SST::Cycle_t currentCycle ) {
 
-	if( currentCycle % printFreq == 0 ) {
-		output.verbose(CALL_INFO, 1, 0, "Hello World!\n");
-	}
+    if( currentCycle % printFreq == 0 ) {
+        output.verbose(CALL_INFO, 1, 0, "Hello World!\n");
+    }
 
-	repeats++;
+    repeats++;
 
-	if( repeats == maxRepeats ) {
-		primaryComponentOKToEndSim();
-		return true;
-	} else {
-		return false;
-	}
+    if( repeats == maxRepeats ) {
+        primaryComponentOKToEndSim();
+	return true;    // Stop calling this clock handler
+    } else {
+	return false;   // Keep calling this clock handler
+    }
 }
diff --git a/src/simpleExternalElement.h b/src/simpleExternalElement.h
@@ -1,8 +1,8 @@
-// Copyright 2009-2023 NTESS. Under the terms
+// Copyright 2009-2024 NTESS. Under the terms
 // of Contract DE-NA0003525 with NTESS, the U.S.
 // Government retains certain rights in this software.
 //
-// Copyright (c) 2009-2023, NTESS
+// Copyright (c) 2009-2024, NTESS
 // All rights reserved.
 //
 // This file is part of the SST software package. For license
@@ -13,33 +13,65 @@
 #define _SIMPLE_EXTERNAL_ELEMENT_H
 
 #include <sst/core/component.h>
-#include <sst/core/eli/elementinfo.h>
 
 class SimpleExternalElement : public SST::Component {
 
 public:
-	SimpleExternalElement( SST::ComponentId_t id, SST::Params& params );
-	~SimpleExternalElement();
-
-	void setup();
-	void finish();
-
-	bool clockTick( SST::Cycle_t currentCycle );
-
+/* SST ELI macros */
+        /* Register component */
 	SST_ELI_REGISTER_COMPONENT(
-		SimpleExternalElement,
-		"simpleExternalElement",
-		"SimpleExternalElement",
-		SST_ELI_ELEMENT_VERSION( 1, 0, 0 ),
-		"Demonstration of an External Element for SST",
-		COMPONENT_CATEGORY_PROCESSOR
+		SimpleExternalElement,              // Class name
+		"simpleExternalElement",            // Name of library
+		"SimpleExternalElement",            // Lookup name for component
+		SST_ELI_ELEMENT_VERSION( 1, 0, 0 ), // Component version
+                "Demonstration of an External Element for SST", // Description
+		COMPONENT_CATEGORY_PROCESSOR    // Other options: 
+                                                //      COMPONENT_CATEGORY_MEMORY, 
+                                                //      COMPONENT_CATEGORY_NETWORK, 
+                                                //      COMPONENT_CATEGORY_UNCATEGORIZED
 	)
 
+        /* 
+         * Document parameters. 
+         *  Required parameter format: { "paramname", "description", NULL }
+         *  Optional parameter format: { "paramname", "description", "default value"}
+         */
 	SST_ELI_DOCUMENT_PARAMS(
 		{ "printFrequency", "How frequently to print a message from the component", "5" },
 		{ "repeats", "Number of repetitions to make", "10" }
 	)
 
+        /* Document ports (optional if no ports declared)
+         *  Format: { "portname", "description", { "eventtype0", "eventtype1" } }
+         */
+        SST_ELI_DOCUMENT_PORTS( )
+
+        /* Document statistics (optional if no statistics declared)
+         *  Format: { "statisticname", "description", "units", "enablelevel" }
+         */
+        SST_ELI_DOCUMENT_STATISTICS( )
+
+        /* Document subcomponent slots (optional if no subcomponent slots declared)
+         *  Format: { "slotname", "description", "subcomponentAPI" }
+         */
+        SST_ELI_DOCUMENT_SUBCOMPONENT_SLOTS( )
+
+/* Class members */
+        // Constructor
+	SimpleExternalElement( SST::ComponentId_t id, SST::Params& params );
+
+        // Destructor
+        ~SimpleExternalElement();
+
+        // SST lifecycle functions (optional if not used)
+	virtual void init(unsigned int phase) override;
+        virtual void setup() override;
+        virtual void complete(unsigned int phase) override;
+	virtual void finish() override;
+
+        // Clock handler
+	bool clockTick( SST::Cycle_t currentCycle );
+
 private:
 	SST::Output output;
 	SST::Cycle_t printFreq;

diff --git a/tests/refFiles/simpleElementExample-test-001.out b/tests/refFiles/simpleElementExample-test-001.out
@@ -1,8 +1,10 @@
 WARNING: Building component "simpleExternalElement" with no links assigned.
 SimpleExternalElement-simpleExternalElement-> Config: maxRepeats=15, printFreq=5
+SimpleExternalElement-simpleExternalElement-> Component is participating in phase 0 of init.
 SimpleExternalElement-simpleExternalElement-> Component is being setup.
 SimpleExternalElement-simpleExternalElement-> Hello World!
 SimpleExternalElement-simpleExternalElement-> Hello World!
 SimpleExternalElement-simpleExternalElement-> Hello World!
+SimpleExternalElement-simpleExternalElement-> Component is participating in phase 0 of complete.
 SimpleExternalElement-simpleExternalElement-> Component is being finished.
 Simulation is complete, simulated time: 150 ns