Debian Codegraph @

include/deal.II/base/conditional_ostream.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2004 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_conditional_ostream_h
16 #define dealii_conditional_ostream_h
17
18 #include <deal.II/base/config.h>
19
20 #include <ostream>
21
22 DEAL_II_NAMESPACE_OPEN
23
24
25 /**
26 * A class that allows printing to an output stream, e.g. @p std::cout,
27 * depending on the ConditionalOStream object being active (default) or not.
28 * The condition of this object can be changed by set_condition() and in the
29 * constructor. This class is used in the step-17, step-18, step-32, step-33,
30 * and step-35 tutorial programs.
31 *
32 * This class is mostly useful in parallel computations. Ordinarily, you would
33 * use @p std::cout to print messages like what the program is presently
34 * doing, or the number of degrees of freedom in each step. However, in
35 * parallel programs, this means that each of the MPI processes write to the
36 * screen, which yields many repetitions of the same text. To avoid it, one
37 * would have to have a designated process, say the one with MPI process
38 * number zero, do the output, and guard each write statement with an
39 * if-condition. This becomes cumbersome and clutters up the code. Rather than
40 * doing so, the present class can be used: objects of its type act just like
41 * a standard output stream, but they only print something based on a
42 * condition that can be set to, for example, <tt>mpi_process==0</tt>, so that
43 * only one process has a true condition and in all other processes writes to
44 * this object just disappear in nirvana.
45 *
46 * The usual usage of this class is as follows:
47 *
48 * @code
49 * ConditionalOStream pout(std::cout, this_mpi_process==0);
50 *
51 * // all processes print the following information to standard output
52 * std::cout << "Reading parameter file on process "
53 * << this_mpi_process << std::endl;
54 *
55 * // following is printed by process 0 only
56 * pout << "Solving ..." << std::endl;
57 * solve();
58 * pout << "done" << std::endl;
59 * @endcode
60 *
61 * Here, `Reading parameter file on process xy' is printed by each process
62 * separately. In contrast to that, `Solving ...' and `done' is printed to
63 * standard output only once, namely by process 0.
64 *
65 * This class is not derived from ostream. Therefore
66 * @code
67 * system_matrix.print_formatted(pout);
68 * @endcode
69 * is <em>not</em> possible. Instead use the is_active() function for a
70 * work-around:
71 *
72 * @code
73 * if (pout.is_active())
74 * system_matrix.print_formatted(cout);
75 * @endcode
76 *
77 * @ingroup textoutput
78 */
79 class ConditionalOStream
80 {
81 public:
82 /**
83 * Constructor. Set the stream to which we want to write, and the condition
84 * based on which writes are actually forwarded. Per default the condition
85 * of an object is active.
86 */
87 explicit ConditionalOStream(std::ostream &stream, const bool active = true);
88
89 /**
90 * Depending on the <tt>active</tt> flag set the condition of this stream to
91 * active (true) or non-active (false). An object of this class prints to
92 * <tt>cout</tt> if and only if its condition is active.
93 */
94 void
95 set_condition(const bool active);
96
97 /**
98 * Return the condition of the object.
99 */
100 bool
101 is_active() const;
102
103 /**
104 * Return a reference to the stream currently in use.
105 */
106 std::ostream &
107 get_stream() const;
108
109 /**
110 * Output a constant something through this stream. This function must be @p
111 * const so that member objects of this type can also be used from @p const
112 * member functions of the surrounding class.
113 */
114 template <typename T>
115 const ConditionalOStream &
116 operator<<(const T &t) const;
117
118 /**
119 * Treat ostream manipulators. This function must be @p const so that member
120 * objects of this type can also be used from @p const member functions of
121 * the surrounding class.
122 *
123 * Note that compilers want to see this treated differently from the general
124 * template above since functions like @p std::endl are actually overloaded
125 * and can't be bound directly to a template type.
126 */
127 const ConditionalOStream &
128 operator<<(std::ostream &(*p)(std::ostream &)) const;
129
130 private:
131 /**
132 * Reference to the stream we want to write to.
133 */
134 std::ostream &output_stream;
135
136 /**
137 * Stores the actual condition the object is in.
138 */
139 bool active_flag;
140 };
141
142
143 // --------------------------- inline and template functions -----------
144
145 template <class T>
146 inline const ConditionalOStream &
147 ConditionalOStream::operator<<(const T &t) const
148 {
149 if (active_flag == true)
150 output_stream << t;
151
152 return *this;
153 }
154
155
156 inline const ConditionalOStream &
157 ConditionalOStream::operator<<(std::ostream &(*p)(std::ostream &)) const
158 {
159 if (active_flag == true)
160 output_stream << p;
161
162 return *this;
163 }
164
165
166 inline std::ostream &
167 ConditionalOStream::get_stream() const
168 {
169 return output_stream;
170 }
171
172
173 DEAL_II_NAMESPACE_CLOSE
174
175 #endif