A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
sqlite-output.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Natale Patriciello <natale.patriciello@gmail.com>
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 */
7#ifndef SQLITE_OUTPUT_H
8#define SQLITE_OUTPUT_H
9
10#include "ns3/simple-ref-count.h"
11
12#include <mutex>
13#include <sqlite3.h>
14#include <string>
15
16namespace ns3
17{
18
19/**
20 * @ingroup stats
21 *
22 * @brief A C++ interface towards an SQLITE database
23 *
24 * The class is able to execute commands, and retrieve results, from an SQLITE
25 * database. The methods with the "Spin" prefix, in case of concurrent access
26 * to the database, will spin until the operation is applied. The methods with
27 * the "Wait" prefix will wait on a mutex.
28 *
29 * If you run multiple simulations that write on the same database, it is
30 * recommended to use the "Wait" prefixed methods. Otherwise, if the access to
31 * the database is unique, using "Spin" methods will speed up database access.
32 *
33 * The database is opened in the constructor, and closed in the deconstructor.
34 */
35class SQLiteOutput : public SimpleRefCount<SQLiteOutput>
36{
37 public:
38 /**
39 * @brief SQLiteOutput constructor
40 * @param name database name
41 */
42 SQLiteOutput(const std::string& name);
43
44 /**
45 * Destructor
46 */
48
49 /**
50 * @brief Instruct SQLite to store the journal in memory. May lead to data losses
51 * in case of unexpected program exits.
52 */
53 void SetJournalInMemory();
54
55 /**
56 * @brief Execute a command until the return value is OK or an ERROR
57 *
58 * Ignore errors due to concurrency, the method will repeat the command instead
59 *
60 * @param cmd Command
61 * @return true in case of success
62 */
63 bool SpinExec(const std::string& cmd) const;
64
65 /**
66 * @brief Execute a command until the return value is OK or an ERROR
67 * @param stmt SQLite statement
68 * @return true in case of success
69 */
70 bool SpinExec(sqlite3_stmt* stmt) const;
71
72 /**
73 * @brief Execute a command, waiting on a mutex
74 * @param cmd Command to be executed
75 * @return true in case of success
76 */
77 bool WaitExec(const std::string& cmd) const;
78
79 /**
80 * @brief Execute a command, waiting on a mutex
81 * @param stmt Sqlite3 statement to be executed
82 * @return true in case of success
83 */
84 bool WaitExec(sqlite3_stmt* stmt) const;
85
86 /**
87 * @brief Prepare a statement, waiting on a mutex
88 * @param stmt Sqlite statement
89 * @param cmd Command to prepare inside the statement
90 * @return true in case of success
91 */
92 bool WaitPrepare(sqlite3_stmt** stmt, const std::string& cmd) const;
93
94 /**
95 * @brief Prepare a statement
96 * @param stmt Sqlite statement
97 * @param cmd Command to prepare inside the statement
98 * @return true in case of success
99 */
100 bool SpinPrepare(sqlite3_stmt** stmt, const std::string& cmd) const;
101
102 /**
103 * @brief Bind a value to a sqlite statement
104 * @param stmt Sqlite statement
105 * @param pos Position of the bind argument inside the statement
106 * @param value Value to bind
107 * @return true on success, false otherwise
108 */
109 template <typename T>
110 bool Bind(sqlite3_stmt* stmt, int pos, const T& value) const;
111
112 /**
113 * @brief Retrieve a value from an executed statement
114 * @param stmt sqlite statement
115 * @param pos Column position
116 * @return the value from the executed statement
117 */
118 template <typename T>
119 T RetrieveColumn(sqlite3_stmt* stmt, int pos) const;
120
121 /**
122 * @brief Execute a step operation on a statement until the result is ok or an error
123 *
124 * Ignores concurrency errors; it will retry instead of failing.
125 *
126 * @param stmt Statement
127 * @return Sqlite error core
128 */
129
130 static int SpinStep(sqlite3_stmt* stmt);
131 /**
132 * @brief Finalize a statement until the result is ok or an error
133 *
134 * Ignores concurrency errors; it will retry instead of failing.
135 *
136 * @param stmt Statement
137 * @return Sqlite error code
138 */
139 static int SpinFinalize(sqlite3_stmt* stmt);
140
141 /**
142 * @brief Reset a statement until the result is ok or an error
143 *
144 * Ignores concurrency errors: it will retry instead of failing.
145 * @param stmt Statement
146 * @return the return code of reset
147 */
148 static int SpinReset(sqlite3_stmt* stmt);
149
150 protected:
151 /**
152 * @brief Execute a command, waiting on a mutex
153 * @param db Database
154 * @param cmd Command
155 * @return Sqlite error code
156 */
157 int WaitExec(sqlite3* db, const std::string& cmd) const;
158
159 /**
160 * @brief Execute a statement, waiting on a mutex
161 * @param db Database
162 * @param stmt Statement
163 * @return Sqlite error code
164 */
165 int WaitExec(sqlite3* db, sqlite3_stmt* stmt) const;
166
167 /**
168 * @brief Prepare a statement, waiting on a mutex
169 * @param db Database
170 * @param stmt Statement
171 * @param cmd Command to prepare
172 * @return Sqlite error code
173 */
174 int WaitPrepare(sqlite3* db, sqlite3_stmt** stmt, const std::string& cmd) const;
175
176 /**
177 * @brief Execute a command ignoring concurrency problems, retrying instead
178 * @param db Database
179 * @param cmd Command
180 * @return Sqlite error code
181 */
182 static int SpinExec(sqlite3* db, const std::string& cmd);
183
184 /**
185 * @brief Execute a Prepared Statement Object ignoring concurrency problems, retrying instead
186 * @param db Database
187 * @param stmt Prepared Statement Object
188 * @return Sqlite error code
189 */
190 static int SpinExec(sqlite3* db, sqlite3_stmt* stmt);
191
192 /**
193 * @brief Preparing a command ignoring concurrency problems, retrying instead
194 * @param db Database
195 * @param stmt Statement
196 * @param cmd Command to prepare
197 * @return Sqlite error code
198 */
199 static int SpinPrepare(sqlite3* db, sqlite3_stmt** stmt, const std::string& cmd);
200
201 /**
202 * @brief Fail, printing an error message from sqlite
203 * @param db Database
204 * @param cmd Command
205 */
206 [[noreturn]] static void Error(sqlite3* db, const std::string& cmd);
207
208 /**
209 * @brief Check any error in the db
210 * @param db Database
211 * @param rc Sqlite return code
212 * @param cmd Command
213 * @param hardExit if true, will exit the program
214 * @return true in case of error, false otherwise
215 */
216 static bool CheckError(sqlite3* db, int rc, const std::string& cmd, bool hardExit);
217
218 private:
219 std::string m_dBname; //!< Database name
220 mutable std::mutex m_mutex; //!< Mutex
221 sqlite3* m_db{nullptr}; //!< Database pointer
222};
223
224} // namespace ns3
225#endif
A C++ interface towards an SQLITE database.
sqlite3 * m_db
Database pointer.
std::string m_dBname
Database name.
bool SpinExec(const std::string &cmd) const
Execute a command until the return value is OK or an ERROR.
static bool CheckError(sqlite3 *db, int rc, const std::string &cmd, bool hardExit)
Check any error in the db.
~SQLiteOutput()
Destructor.
static int SpinStep(sqlite3_stmt *stmt)
Execute a step operation on a statement until the result is ok or an error.
void SetJournalInMemory()
Instruct SQLite to store the journal in memory.
T RetrieveColumn(sqlite3_stmt *stmt, int pos) const
Retrieve a value from an executed statement.
bool Bind(sqlite3_stmt *stmt, int pos, const T &value) const
Bind a value to a sqlite statement.
static int SpinReset(sqlite3_stmt *stmt)
Reset a statement until the result is ok or an error.
static int SpinFinalize(sqlite3_stmt *stmt)
Finalize a statement until the result is ok or an error.
std::mutex m_mutex
Mutex.
bool WaitExec(const std::string &cmd) const
Execute a command, waiting on a mutex.
static void Error(sqlite3 *db, const std::string &cmd)
Fail, printing an error message from sqlite.
bool SpinPrepare(sqlite3_stmt **stmt, const std::string &cmd) const
Prepare a statement.
SQLiteOutput(const std::string &name)
SQLiteOutput constructor.
bool WaitPrepare(sqlite3_stmt **stmt, const std::string &cmd) const
Prepare a statement, waiting on a mutex.
A template-based reference counting class.
Every class exported by the ns3 library is enclosed in the ns3 namespace.