A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
output-stream-wrapper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2010 University of Washington
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 */
6
7#ifndef OUTPUT_STREAM_WRAPPER_H
8#define OUTPUT_STREAM_WRAPPER_H
9
10#include "ns3/object.h"
11#include "ns3/ptr.h"
12#include "ns3/simple-ref-count.h"
13
14#include <fstream>
15
16namespace ns3
17{
18
19/**
20 * @brief A class encapsulating an output stream.
21 *
22 * This class wraps a pointer to a C++ std::ostream and provides
23 * reference counting of the object. This class is recommended for users
24 * who want to pass output streams in the ns-3 APIs, such as in callbacks
25 * or tracing.
26 *
27 * This class is motivated by the fact that in C++, copy and assignment of
28 * iostreams is forbidden by std::basic_ios<>, because it is not possible
29 * to predict the semantics of the stream desired by a user.
30 *
31 * When writing traced information to a file, the tempting ns-3 idiom is to
32 * create a bound callback with an ofstream as the bound object. Unfortunately,
33 * this implies a copy construction in order to get the ofstream object into the
34 * callback. This operation, as mentioned above, is forbidden by the STL.
35 * Using this class in ns-3 APIs is generally preferable to passing global
36 * pointers to ostream objects, or passing a pointer to a stack allocated
37 * ostream (which creates object lifetime issues).
38 *
39 * One could imagine having this object inherit from stream to get the various
40 * overloaded operator<< defined, but we're going to be using a
41 * Ptr<OutputStreamWrapper> when passing this object around. In this case, the
42 * Ptr<> wouldn't understand the operators and we would have to dereference it
43 * to access the underlying object methods. Since we would have to dereference
44 * the Ptr<>, we don't bother and just expect the user to Get a saved pointer
45 * to an ostream and dereference it him or herself. As in:
46 *
47 * \code{.cpp}
48 * void
49 * TraceSink(Ptr<OutputStreamWrapper> streamWrapper, Ptr<const Packet> packet)
50 * {
51 * std::ostream *stream = streamWrapper->GetStream();
52 * *stream << "got packet" << std::endl;
53 * }
54 * \endcode
55 *
56 *
57 * This class uses a basic ns-3 reference counting base class but is not
58 * an ns3::Object with attributes, TypeId, or aggregation.
59 */
60class OutputStreamWrapper : public SimpleRefCount<OutputStreamWrapper>
61{
62 public:
63 /**
64 * Constructor
65 * \param filename file name
66 * \param filemode std::ios::openmode flags
67 */
68 OutputStreamWrapper(std::string filename, std::ios::openmode filemode);
69 /**
70 * Constructor
71 * \param os output stream
72 */
73 OutputStreamWrapper(std::ostream* os);
75
76 /**
77 * Return a pointer to an ostream previously set in the wrapper.
78 *
79 * \see SetStream
80 *
81 * \returns a pointer to the encapsulated std::ostream
82 */
83 std::ostream* GetStream();
84
85 private:
86 std::ostream* m_ostream; //!< The output stream
87 bool m_destroyable; //!< Can be destroyed
88};
89
90} // namespace ns3
91
92#endif /* OUTPUT_STREAM_WRAPPER_H */
A class encapsulating an output stream.
OutputStreamWrapper(std::string filename, std::ios::openmode filemode)
Constructor.
std::ostream * GetStream()
Return a pointer to an ostream previously set in the wrapper.
bool m_destroyable
Can be destroyed.
std::ostream * m_ostream
The output stream.
A template-based reference counting class.
Every class exported by the ns3 library is enclosed in the ns3 namespace.