KiCad PCB EDA Suite
Loading...
Searching...
No Matches
sch_io_database.h
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 2022 Jon Evans <[email protected]>
5 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
6 *
7 * This program is free software: you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation, either version 3 of the License, or (at your
10 * option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <https://www.gnu.org/licenses/>.
19 */
20
21#ifndef SCH_IO_DATABASE_H_
22#define SCH_IO_DATABASE_H_
23
25#include <sch_io/sch_io.h>
26#include <sch_io/sch_io_mgr.h>
28#include <atomic>
29#include <chrono>
30#include <condition_variable>
31#include <functional>
32#include <mutex>
33#include <optional>
34#include <random>
35#include <shared_mutex>
36#include <thread>
37#include <unordered_set>
38
39
40class LIB_ID;
44struct DATABASE_SOURCE;
45
46
54class SCH_IO_DATABASE : public SCH_IO
55{
57
58public:
59
61 virtual ~SCH_IO_DATABASE();
62
64 {
65 return IO_BASE::IO_FILE_DESC( _HKI( "KiCad database library files" ),
67 }
68
69 int GetModifyHash() const override { return m_modifyHash; }
70
71 void EnumerateSymbolLib( wxArrayString& aSymbolNameList,
72 const wxString& aLibraryPath,
73 const std::map<std::string, UTF8>* aProperties = nullptr ) override;
74
75 void EnumerateSymbolLib( std::vector<LIB_SYMBOL*>& aSymbolList,
76 const wxString& aLibraryPath,
77 const std::map<std::string, UTF8>* aProperties = nullptr ) override;
78
79 void CheckLibrary( const wxString& aLibraryPath,
80 const std::map<std::string, UTF8>* aProperties = nullptr ) override;
81
82 LIB_SYMBOL* LoadSymbol( const wxString& aLibraryPath, const wxString& aAliasName,
83 const std::map<std::string, UTF8>* aProperties = nullptr ) override;
84
85 bool SupportsSubLibraries() const override { return true; }
86
87 void GetSubLibraryNames( std::vector<wxString>& aNames ) override;
88
89 void GetAvailableSymbolFields( std::vector<wxString>& aNames ) override;
90
91 void GetDefaultSymbolFields( std::vector<wxString>& aNames ) override;
92
93 // Database libraries can never be written using the symbol editing API
94 bool IsLibraryWritable( const wxString& aLibraryPath ) override { return false; }
95
97 {
98 m_adapter = aAdapter;
99 }
100
101 bool SupportsConfigurationDialog() const override { return true; }
102
103 DIALOG_SHIM* CreateConfigurationDialog( wxWindow* aParent, const wxString& aLibraryPath ) override;
104
107 void CancelLoad() override;
108
109 void ResumeLoad() noexcept override;
110
112
113 DATABASE_LIB_SETTINGS* Settings() const { return m_settings.get(); }
114
116 static wxString SymbolNameForRow( const DATABASE_LIB_TABLE& aTable, bool aGloballyUniqueKeys,
117 const DATABASE_CONNECTION::ROW& aRow, std::string* aRawKey = nullptr );
118
121 {
123 std::unique_ptr<DATABASE_CONNECTION> connection;
124
127
129 std::string error;
130 };
131
139 static CONNECTION_RESULT CreateConnection( const DATABASE_LIB_SETTINGS& aSettings, bool aConnectNow = true,
140 const wxString& aBaseDir = wxEmptyString );
141
144 {
152
154 wxString message;
155 };
156
157 using PREVIEW_ISSUES = std::vector<PREVIEW_ISSUE>;
158
167 static std::vector<std::unique_ptr<LIB_SYMBOL>>
168 BuildPreviewSymbols( SYMBOL_LIBRARY_ADAPTER* aLibs, const DATABASE_LIB_TABLE& aTable, bool aGloballyUniqueKeys,
169 const std::vector<DATABASE_CONNECTION::ROW>& aRows, PREVIEW_ISSUES* aIssues );
170
171private:
172 typedef std::vector<std::pair<const DATABASE_LIB_TABLE*, std::vector<DATABASE_CONNECTION::ROW>>> TABLE_RESULT_LIST;
173
174 void cacheLib( const std::shared_ptr<DATABASE_CONNECTION>& aConn );
175
176 size_t computeSignature( const TABLE_RESULT_LIST& aTableResults ) const;
177
178 bool materializeCache( const TABLE_RESULT_LIST& aTableResults,
179 std::map<wxString, std::unique_ptr<LIB_SYMBOL>>& aSymbolCache,
180 std::map<wxString, std::pair<std::string, std::string>>& aSanitizedNameMap );
181
182 void ensureSettings( const wxString& aSettingsPath );
183
186 void loadSettingsBounded( int aTimeoutSeconds );
187
194
196 std::shared_ptr<DATABASE_CONNECTION> currentConnection();
197
199 std::shared_ptr<DATABASE_CONNECTION> ensureConnection();
200
203
206
208 bool connectionStopped() const;
209
211 static CONNECTION_RESULT connectionFor( DB_BACKEND_RESULT&& aBackend, bool aConnectNow );
212
213 std::unique_ptr<LIB_SYMBOL> loadSymbolFromRow( const wxString& aSymbolName,
214 const DATABASE_LIB_TABLE& aTable,
215 const DATABASE_CONNECTION::ROW& aRow );
216
217 static std::optional<bool> boolFromAny( const std::any& aVal );
218
221
223 void reportIssue( PREVIEW_ISSUE::FIELD aField, const wxString& aMessage, SEVERITY aSeverity ) const;
224
226 bool m_previewMode = false;
227
230
232
233 std::unique_ptr<DATABASE_LIB_SETTINGS> m_settings;
234
236 std::shared_ptr<DATABASE_CONNECTION> m_conn;
237
238 std::set<wxString> m_customFields;
239
240 std::set<wxString> m_defaultShownFields;
241
242 std::map<wxString, std::unique_ptr<LIB_SYMBOL>> m_nameToSymbolcache;
243 std::map<wxString, std::pair<std::string, std::string>> m_sanitizedNameMap;
244
246
248 std::atomic<bool> m_cachePopulated{ false };
249
251
255
260 static thread_local std::unordered_set<wxString> s_inProgressLoads;
261
264 bool m_inCacheLib = false;
265
269
271 static constexpr int MAX_BUSY_ATTEMPT = 5;
272
277 static std::chrono::milliseconds busyRetryWait( long long aMaxAgeSeconds, int aAttempt, std::minstd_rand& aRng );
278
280 static constexpr std::chrono::seconds FIRST_CONNECT_BUDGET{ 3 };
281
282 std::thread m_refreshThread;
283 std::atomic<bool> m_refreshRunning{ false };
284 std::atomic<bool> m_stopping{ false };
285 std::atomic<bool> m_loadCancelled{ false };
286
287 std::condition_variable m_refreshCV;
288 std::mutex m_refreshMutex;
289 std::shared_mutex m_cacheMutex;
290 std::mutex m_connectMutex;
292};
293
294#endif //SCH_IO_DATABASE_H_
std::map< std::string, std::any > ROW
Dialog helper object to sit in the inheritance tree between wxDialog and any class written by wxFormB...
Definition dialog_shim.h:81
The interface used by the classes that actually can load IO plugins for the different parts of KiCad ...
A logical library item identifier and consists of various portions much like a URI.
Definition lib_id.h:45
Define a library symbol object.
Definition lib_symbol.h:114
void reportIssue(PREVIEW_ISSUE::FIELD aField, const wxString &aMessage, SEVERITY aSeverity) const
Reports to the preview's issue list when there is one, otherwise to the reporter.
void EnumerateSymbolLib(wxArrayString &aSymbolNameList, const wxString &aLibraryPath, const std::map< std::string, UTF8 > *aProperties=nullptr) override
Populate a list of LIB_SYMBOL alias names contained within the library aLibraryPath.
CONNECT_STATUS connect()
Connects, and waits out a file another instance is opening at the same moment when the library never ...
DIALOG_SHIM * CreateConfigurationDialog(wxWindow *aParent, const wxString &aLibraryPath) override
std::shared_mutex m_cacheMutex
void StopBackgroundRefresh() override
Stop and join any thread that reads other libraries through the library adapter.
PREVIEW_ISSUES * m_previewIssues
Collects the problems found while building a preview; null outside BuildPreviewSymbols()
std::mutex m_connectMutex
DATABASE_LIB_SETTINGS * Settings() const
std::shared_ptr< DATABASE_CONNECTION > m_conn
Generally will be null if no valid connection is established.
void CancelLoad() override
Ends the waits of a load in progress and of any that starts before ResumeLoad(), so closing a project...
friend class SCH_IO_DATABASE_CYCLE_DETECTION_FIXTURE
static wxString SymbolNameForRow(const DATABASE_LIB_TABLE &aTable, bool aGloballyUniqueKeys, const DATABASE_CONNECTION::ROW &aRow, std::string *aRawKey=nullptr)
void GetDefaultSymbolFields(std::vector< wxString > &aNames) override
Retrieves a list of (custom) field names that should be shown by default for this library in the symb...
void loadSettingsBounded(int aTimeoutSeconds)
Loads the settings file on a thread that can be abandoned, so a share that went away cannot hold the ...
void ensureSettings(const wxString &aSettingsPath)
static thread_local std::unordered_set< wxString > s_inProgressLoads
LIB_IDs whose resolution is in flight on the calling thread, used to break self-referential cycles wh...
bool IsLibraryWritable(const wxString &aLibraryPath) override
Return true if the library at aLibraryPath is writable.
std::shared_ptr< DATABASE_CONNECTION > currentConnection()
Copies the connection under the cache lock so the caller keeps it alive across a reconnect.
std::atomic< bool > m_loadCancelled
Set by CancelLoad(), cleared by ResumeLoad()
bool SupportsSubLibraries() const override
static std::vector< std::unique_ptr< LIB_SYMBOL > > BuildPreviewSymbols(SYMBOL_LIBRARY_ADAPTER *aLibs, const DATABASE_LIB_TABLE &aTable, bool aGloballyUniqueKeys, const std::vector< DATABASE_CONNECTION::ROW > &aRows, PREVIEW_ISSUES *aIssues)
Builds symbols from already-fetched rows exactly as the library would name and load them,...
std::atomic< bool > m_cachePopulated
True once the LIB_SYMBOL cache has been materialized at least once.
bool m_inCacheLib
Re-entrancy guard for cacheLib(), tripped when a self-referential load routes back through the adapte...
std::map< wxString, std::unique_ptr< LIB_SYMBOL > > m_nameToSymbolcache
std::map< wxString, std::pair< std::string, std::string > > m_sanitizedNameMap
CONNECT_STATUS connectOnce()
One attempt at connect(), with m_connectMutex held.
std::set< wxString > m_defaultShownFields
void SetLibraryManagerAdapter(SYMBOL_LIBRARY_ADAPTER *aAdapter) override
Some library plugins need to interface with other loaded libraries.
virtual ~SCH_IO_DATABASE()
void cacheLib(const std::shared_ptr< DATABASE_CONNECTION > &aConn)
size_t m_cacheSignature
Signature of the raw database rows at last materialization; used to skip rebuilding the LIB_SYMBOL ca...
std::vector< std::pair< const DATABASE_LIB_TABLE *, std::vector< DATABASE_CONNECTION::ROW > > > TABLE_RESULT_LIST
bool connectionStopped() const
static CONNECTION_RESULT CreateConnection(const DATABASE_LIB_SETTINGS &aSettings, bool aConnectNow=true, const wxString &aBaseDir=wxEmptyString)
Opens a connection described by aSettings, expanding ${CWD} in a connection string to the directory h...
void GetSubLibraryNames(std::vector< wxString > &aNames) override
Retrieves a list of sub-libraries in this library.
static std::chrono::milliseconds busyRetryWait(long long aMaxAgeSeconds, int aAttempt, std::minstd_rand &aRng)
std::unique_ptr< DATABASE_LIB_SETTINGS > m_settings
bool SupportsConfigurationDialog() const override
static std::optional< bool > boolFromAny(const std::any &aVal)
size_t computeSignature(const TABLE_RESULT_LIST &aTableResults) const
void CheckLibrary(const wxString &aLibraryPath, const std::map< std::string, UTF8 > *aProperties=nullptr) override
Validate that the library at aLibraryPath is reachable and well-formed, without necessarily loading s...
SYMBOL_LIBRARY_ADAPTER * m_adapter
std::thread m_refreshThread
const IO_BASE::IO_FILE_DESC GetLibraryDesc() const override
Get the descriptor for the library container that this IO plugin operates on.
static constexpr int MAX_BUSY_ATTEMPT
Busy retries past this attempt stop doubling the window.
long long m_cacheTimestamp
std::condition_variable m_refreshCV
void GetAvailableSymbolFields(std::vector< wxString > &aNames) override
Retrieves a list of (custom) field names that are present on symbols in this library.
std::atomic< bool > m_refreshRunning
bool m_previewMode
Set on the throwaway instance behind BuildPreviewSymbols()
std::atomic< bool > m_stopping
int GetModifyHash() const override
Return the modification hash from the library cache.
bool materializeCache(const TABLE_RESULT_LIST &aTableResults, std::map< wxString, std::unique_ptr< LIB_SYMBOL > > &aSymbolCache, std::map< wxString, std::pair< std::string, std::string > > &aSanitizedNameMap)
std::unique_ptr< LIB_SYMBOL > loadSymbolFromRow(const wxString &aSymbolName, const DATABASE_LIB_TABLE &aTable, const DATABASE_CONNECTION::ROW &aRow)
static constexpr std::chrono::seconds FIRST_CONNECT_BUDGET
The race this covers lasts milliseconds, so a file in use for longer has a real holder and is reporte...
static CONNECTION_RESULT connectionFor(DB_BACKEND_RESULT &&aBackend, bool aConnectNow)
Wraps a backend in a connection, or reports why there is none.
void ResumeLoad() noexcept override
Called after the loads that were cancelled have ended, to clear what CancelLoad() left behind.
std::set< wxString > m_customFields
std::mutex m_symbolLoadMutex
LIB_SYMBOL * resolveSourceSymbol(const LIB_ID &aId)
Resolves one entry of a row's symbols column through the library adapter.
std::shared_ptr< DATABASE_CONNECTION > ensureConnection()
Returns a live connection or throws.
std::vector< PREVIEW_ISSUE > PREVIEW_ISSUES
LIB_SYMBOL * LoadSymbol(const wxString &aLibraryPath, const wxString &aAliasName, const std::map< std::string, UTF8 > *aProperties=nullptr) override
Load a LIB_SYMBOL object having aPartName from the aLibraryPath containing a library format that this...
std::mutex m_refreshMutex
SCH_IO(const wxString &aName)
Definition sch_io.h:406
An interface to the global shared library manager that is schematic-specific and linked to one projec...
DB_FAILURE
Why a connection attempt failed, as far as the backend's report tells.
static const std::string DatabaseLibraryFileExtension
#define _HKI(x)
Definition page_info.cpp:40
SEVERITY
A database library table will be mapped to a sub-library provided by the database library entry in th...
The outcome of building a backend; backend is null when failure and error say why.
Container that describes file type info.
Definition io_base.h:43
A connection built from settings, or the reason none could be built.
std::unique_ptr< DATABASE_CONNECTION > connection
Null when no backend exists for the source type.
DB_FAILURE failure
Why connection is null.
std::string error
The message naming the problem when connection is null.
Why the last connect() attempt failed, for the caller to report from its own copy.
A problem found while previewing, tagged with the setting that caused it.
@ KEY
The row as a whole, such as colliding keys or a row that could not be loaded.
@ REPEATED_KEY
A key that more than one row has.
Definition of file extensions used in Kicad.