Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Teuchos_VerboseObjectParameterListHelpers.cpp
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #include "Teuchos_VerboseObjectParameterListHelpers.hpp"
43 #include "Teuchos_StandardParameterEntryValidators.hpp"
44 #include <fstream>
45 
46 namespace {
47 
48 
49 const std::string VerboseObject_name = "VerboseObject";
50 
51 const std::string OutputFile_name = "Output File";
52 const std::string OutputFile_default = "none";
53 
54 const std::string VerbosityLevel_name = "Verbosity Level";
55 const std::string VerbosityLevel_default = "default";
58  >
59 VerbosityLevel_validator;
60 
61 
62 } // namespace
63 
64 
65 
67 Teuchos::getValidVerboseObjectSublist()
68 {
69  using Teuchos::rcp_implicit_cast;
70  static RCP<const ParameterList> validParams;
71  if (is_null(validParams)) {
72  RCP<ParameterList>
73  pl = rcp(new ParameterList(VerboseObject_name));
74  VerbosityLevel_validator = verbosityLevelParameterEntryValidator(VerbosityLevel_name);
75  pl->set(
76  VerbosityLevel_name, VerbosityLevel_default,
77  "The verbosity level to use to override whatever is set in code.\n"
78  "The value of \"default\" will allow the level set in code to be used.",
79  rcp_implicit_cast<const ParameterEntryValidator>(VerbosityLevel_validator)
80  );
81  pl->set(
82  OutputFile_name, OutputFile_default,
83  "The file to send output to. If the value \"none\" is used, then\n"
84  "whatever is set in code will be used. However, any other std::string value\n"
85  "will be used to create an std::ofstream object to a file with the given name.\n"
86  "Therefore, any valid file name is a valid std::string value for this parameter."
87  );
88  validParams = pl;
89  }
90  return validParams;
91 }
92 
93 
94 void Teuchos::setupVerboseObjectSublist( ParameterList* paramList )
95 {
96  TEUCHOS_TEST_FOR_EXCEPT(0==paramList);
97  paramList->sublist(VerboseObject_name).setParameters(
99  ).disableRecursiveValidation();
100 }
101 
102 
103 void Teuchos::readVerboseObjectSublist(
104  ParameterList* paramList,
105  RCP<FancyOStream> *oStream, EVerbosityLevel *verbLevel
106  )
107 {
108  // Validate input
109  TEUCHOS_TEST_FOR_EXCEPT(0==paramList);
110  TEUCHOS_TEST_FOR_EXCEPT(0==oStream);
111  TEUCHOS_TEST_FOR_EXCEPT(0==verbLevel);
112  ParameterList
113  &voSublist = paramList->sublist(VerboseObject_name);
114  voSublist.validateParameters(*getValidVerboseObjectSublist());
115  const std::string
116  outputFileStr = voSublist.get(OutputFile_name,OutputFile_default);
117  *verbLevel = VerbosityLevel_validator->getIntegralValue(
118  voSublist,VerbosityLevel_name,VerbosityLevel_default
119  );
120  // the default file string is nothing
121  if (outputFileStr==OutputFile_default) {
122  *oStream = null;
123  }
124  // if a file is specified then output to an fstream
125  else {
126 
127  // JJE: 14 March 2019
128  // A fix for file output of an VerboseObject.
129  //
130  // This step is very important. With filestreams it does not make
131  // sense for multiple MPI ranks to open the same file. Nor,
132  // does it seem inline with the OStream model that each stream
133  // represent a unique file. Perhaps, if that functionality is desired
134  // then the file name could be suffixed with the MPI Rank.
135  //
136  // A fundamental flaw with this implementation is that we have no knowledge
137  // of a communicator on which this OStream belongs. That makes the idea
138  // of using a rank ambiguous.
139  //
140  // The code below was added, and uses COMM_WORLD, because as-is
141  // this functionality was fundamentally broken. Without restricting
142  // the stream to a single rank, two severe consquences follow:
143  // 1) Each MPI process opens the file, which is not scalable;
144  // 2) Moreover, each MPI process *writes* to the file. Which
145  // can give the illusion that things are working, if each
146  // process writes exactly the same information (e.g., solver
147  // convergence information for a bulk synchronous solve).
148  // This introduces a terrible scalability problem, as the
149  // filesystem is then tasked with coping with concurrent writes
150  // to the same shared file, which is should make you cry a little.
151  //
152  // The resolution, is two fold:
153  // 1st, construct the ostream as a regular wrapper around cout
154  // 2nd, restrict the file creation and opening to a single process
155  // Finally, map all ostreams except the fstream one to
156  // a blackhole. Ensuring each rank has a functional stream
157  // but that only one actually emits data to disk
158  //
159 
160  // this could be a BlackHole, but calling setOutputToRootOnly does slightly
161  // more than simply blackhole output, it also disabled buffering across processes
162  *oStream = Teuchos::fancyOStream(Teuchos::rcpFromRef(std::cout));
163 
164  // Until we resolve OS streams that are communicator aware, use rank 0
165  const int outputFileMPIRank = 0;
166 
167  #if defined(HAVE_TEUCHOS_MPI)
169  #else
170  const int rank = outputFileMPIRank;
171  #endif
172 
173  if ( rank == outputFileMPIRank) {
174  RCP<std::ofstream> oFileStream = rcp(new std::ofstream());
175  // If, in the future we decide to alter buffers, then
176  // change the fstream's buffer before calling open()
177 
178  // open the fstream only on a single MPI process
179  oFileStream->open(outputFileStr);
180 
182  oFileStream->eof(), Exceptions::InvalidParameterValue,
183  "Error, the file \"" << outputFileStr << "\n given by the parameter\n"
184  "\'" << OutputFile_name << "\' in the sublist\n"
185  "\'" << voSublist.name() << "\' count not be opened for output!"
186  );
187  // wrap the fstream inside fancyOStream
188  *oStream = fancyOStream(rcp_implicit_cast<std::ostream>(oFileStream));
189  }
190 
191  #if defined(HAVE_TEUCHOS_MPI)
192  // ensure that only one stream actually emits data
193  (*oStream)->setOutputToRootOnly(outputFileMPIRank);
194  #endif
195  }
196 #ifdef TEUCHOS_DEBUG
197  voSublist.validateParameters(*getValidVerboseObjectSublist());
198 #endif
199 }
RCP< T > rcp(const boost::shared_ptr< T > &sptr)
Conversion function that takes in a boost::shared_ptr object and spits out a Teuchos::RCP object...
static int getRank()
The rank of the calling process in MPI_COMM_WORLD.
RCP< basic_FancyOStream< char > > fancyOStream(const RCP< std::basic_ostream< char > > &oStream, const std::basic_string< char > &tabIndentStr=" ", const int startingTab=0, const bool showLinePrefix=false, const int maxLenLinePrefix=10, const bool showTabCount=false, const bool showProcRank=false)
Dynamically allocate a FancyOStream and return it wrapped in an RCP object.
int rank(const Comm< Ordinal > &comm)
Get the process rank.
Standard implementation of a ParameterEntryValidator that maps from a list of strings to an enum or i...
EVerbosityLevel
Verbosity level.
bool is_null(const ArrayRCP< T > &p)
Returns true if p.get()==NULL.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< const ParameterList > getValidVerboseObjectSublist()
Return the sublist of valid parameters for the &quot;VerboseObject&quot; sublist.
Smart reference counting pointer class for automatic garbage collection.
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)
This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call...
#define TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.