KiCad PCB EDA Suite
Loading...
Searching...
No Matches
library_manager.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 The KiCad Developers, see AUTHORS.txt for contributors.
5 * @author Jon Evans <[email protected]>
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 LIBRARY_MANAGER_H
22#define LIBRARY_MANAGER_H
23
24#include <future>
25#include <memory>
26#include <mutex>
27#include <set>
28#include <shared_mutex>
29
30#include <kicommon.h>
31#include <ki_error.h>
33#include <io/io_base.h>
34
35
36class LIBRARY_MANAGER;
39class PROJECT;
40
41
50
53{
55 std::optional<LIBRARY_ERROR> error = std::nullopt;
56};
57
58
61{
63 std::unique_ptr<IO_BASE> plugin;
64 const LIBRARY_TABLE_ROW* row = nullptr;
66
67 // For an entry in the process-wide globalLibs() cache, the adapter that loaded it and so owns
68 // the lifetime of row. Its destructor evicts the entry; identity is by adapter, not by the
69 // reusable row pointer.
71
72 int modify_hash = -1;
73 std::vector<wxString> available_fields_cache;
74};
75
76
82{
83public:
92
94
95 LIBRARY_MANAGER& Manager() const;
96
98 virtual LIBRARY_TABLE_TYPE Type() const = 0;
99
101 LIBRARY_TABLE* GlobalTable() const;
102
104 std::optional<LIBRARY_TABLE*> ProjectTable() const;
105
106 std::optional<wxString> FindLibraryByURI( const wxString& aURI ) const;
107
109 std::vector<wxString> GetLibraryNames() const;
110
118 bool HasLibrary( const wxString& aNickname, bool aCheckEnabled = false ) const;
119
121 bool DeleteLibrary( const wxString& aNickname );
122
123 std::optional<wxString> GetLibraryDescription( const wxString& aNickname ) const;
124
126 std::vector<LIBRARY_TABLE_ROW*> Rows( LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH,
127 bool aIncludeInvalid = false ) const;
128
130 std::optional<LIBRARY_TABLE_ROW*> GetRow( const wxString& aNickname,
132
134 std::optional<LIBRARY_TABLE_ROW*> FindRowByURI( const wxString& aUri,
136
138 virtual void ProjectChanged();
139
141 void GlobalTablesChanged( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );
142
149 void ProjectTablesChanged( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );
150
155 void ProjectTablesReloaded( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );
156
157 void CheckTableRow( LIBRARY_TABLE_ROW& aRow );
158
160 void AsyncLoad();
161
162 virtual std::optional<LIB_STATUS> LoadOne( LIB_DATA* aLib ) = 0;
163
165 virtual std::optional<LIB_STATUS> CheckLibrary( LIB_DATA* aLib ) { return LoadOne( aLib ); }
166
175 std::optional<float> AsyncLoadProgress() const;
176
177 void BlockUntilLoaded();
178
186 bool RunPreload( PROGRESS_REPORTER& aReporter, std::atomic_bool& aAbort );
187
192 void AbortAsyncLoad( bool aCancelPlugins = false );
193
196 void RestartAsyncLoad();
197
201 void LeakCachesAtExit();
202
203 bool IsLibraryLoaded( const wxString& aNickname );
204
206 std::optional<LIB_STATUS> GetLibraryStatus( const wxString& aNickname ) const;
207
209 std::vector<std::pair<wxString, LIB_STATUS>> GetLibraryStatuses() const;
210
212 std::vector<KI_ERROR> GetLibraryLoadErrors() const;
213
215 void ReloadLibraryEntry( const wxString& aNickname,
217
220 std::optional<LIB_STATUS> LoadLibraryEntry( const wxString& aNickname );
221
223 virtual bool IsWritable( const wxString& aNickname ) const;
224
226 bool CreateLibrary( const wxString& aNickname );
227
232 virtual bool SupportsConfigurationDialog( const LIBRARY_TABLE_ROW& aRow ) const { return false; }
233
239 wxWindow* aParent )
240 {
241 return wxID_CANCEL;
242 }
243
244 virtual std::optional<LIBRARY_ERROR> LibraryError( const wxString& aNickname ) const;
245
246protected:
247 virtual std::map<wxString, LIB_DATA>& globalLibs() = 0;
248 virtual std::map<wxString, LIB_DATA>& globalLibs() const = 0;
249 virtual std::shared_mutex& globalLibsMutex() = 0;
250 virtual std::shared_mutex& globalLibsMutex() const = 0;
251
258 virtual void enumerateLibrary( LIB_DATA* aLib, const wxString& aUri ) = 0;
259
260 wxString getUri( const LIBRARY_TABLE_ROW* aRow ) const;
261
262 std::optional<const LIB_DATA*> fetchIfLoaded( const wxString& aNickname ) const;
263
264 std::optional<LIB_DATA*> fetchIfLoaded( const wxString& aNickname );
265
267 LIBRARY_RESULT<LIB_DATA*> loadIfNeeded( const wxString& aNickname );
268
269 LIBRARY_RESULT<LIB_DATA*> loadFromScope( const wxString& aNickname,
270 LIBRARY_TABLE_SCOPE aScope,
271 std::map<wxString, LIB_DATA>& aTarget,
272 std::shared_mutex& aMutex );
273
279
284 void retireAllLibraries();
285
289 void stopRefreshThreads( std::map<wxString, LIB_DATA>& aLibs, std::shared_mutex& aMutex,
290 const std::function<bool( const wxString& aNickname, const LIB_DATA& aLib )>&
291 aRetiring = {} );
292
296 void abortLoad( bool aCancelPlugins = false );
297
306 void resetProjectCache( bool aCancelPlugins = false );
307
310
311 virtual IO_BASE* plugin( const LIB_DATA* aRow ) = 0;
312
320 static std::recursive_mutex& pluginMutex( const wxString& aNickname );
321
322 using LOADING_KEY = std::pair<wxString, LIBRARY_TABLE_SCOPE>;
323
325 std::vector<LOADING_KEY> loadingSnapshot();
326
328 void cancelLoadingPlugins( const std::vector<LOADING_KEY>& aSnapshot );
329
331 void resumeLoadingPlugins( const std::vector<LOADING_KEY>& aCancelled );
332
334 void withPlugin( const LOADING_KEY& aKey, const std::function<void( IO_BASE& )>& aAction );
335
337
338 // The actual library content is held in an associated IO plugin
339 std::map<wxString, LIB_DATA> m_libraries;
340
341 mutable std::shared_mutex m_librariesMutex;
342
344 std::mutex m_loadingMutex;
345 std::set<LOADING_KEY> m_loading;
346
347 std::atomic_bool m_abort;
348
350 std::atomic_bool m_cancelling{ false };
351
353 std::atomic<unsigned> m_abortGeneration{ 0 };
354
355 std::vector<std::future<void>> m_futures;
356
360 bool m_rearmPending = false;
361
362 std::atomic<size_t> m_loadCount{ 0 };
363 std::atomic<size_t> m_loadTotal{ 0 };
364 std::mutex m_loadMutex;
365
366private:
369 {
370 wxString nickname;
372 wxString uri;
373 };
374
376 void asyncLoadLocked();
377
380 bool loadQueuedRow( const LOAD_WORK& aWork );
381
384 LIB_DATA& queuedRowEntry( const LOAD_WORK& aWork );
385
386 std::shared_mutex& scopeMutex( LIBRARY_TABLE_SCOPE aScope );
387};
388
389
391{
392public:
394 explicit LIBRARY_MANAGER( const PROJECT* aProject = nullptr );
395
396 const PROJECT& Project() const;
397 bool IsProjectScoped() const { return m_project != nullptr; }
398
400
403
404 static wxString DefaultGlobalTablePath( LIBRARY_TABLE_TYPE aType );
405
406 static wxString StockTablePath( LIBRARY_TABLE_TYPE aType );
407
415 static wxString StockTableTokenizedURI( LIBRARY_TABLE_TYPE aType );
416
427 static wxString StockTableReferenceURI( LIBRARY_TABLE_TYPE aType );
428
429 static bool IsTableValid( const wxString& aPath );
430
432 static bool GlobalTablesValid();
433
435 static std::vector<LIBRARY_TABLE_TYPE> InvalidGlobalTables();
436
437 static bool CreateGlobalTable( LIBRARY_TABLE_TYPE aType, bool aPopulateDefaultLibraries );
438
440 void LoadGlobalTables( std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
441
443 void LoadProjectTables( std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
444
445 void ReloadTables( LIBRARY_TABLE_SCOPE aScope, std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
446
448 void ProjectChanged();
449
455 void AbortAsyncLoads( bool aCancelPlugins = false );
456
458 void RestartAsyncLoads();
459
462 void LeakCachesAtExit();
463
464 void RegisterAdapter( LIBRARY_TABLE_TYPE aType,
465 std::unique_ptr<LIBRARY_MANAGER_ADAPTER>&& aAdapter );
466
467 bool RemoveAdapter( LIBRARY_TABLE_TYPE aType, LIBRARY_MANAGER_ADAPTER* aAdapter );
468
469 std::optional<LIBRARY_MANAGER_ADAPTER*> Adapter( LIBRARY_TABLE_TYPE aType ) const;
470
479 std::optional<LIBRARY_TABLE*> Table( LIBRARY_TABLE_TYPE aType,
480 LIBRARY_TABLE_SCOPE aScope );
481
491 std::vector<LIBRARY_TABLE_ROW*> Rows( LIBRARY_TABLE_TYPE aType,
493 bool aIncludeInvalid = false ) const;
494
502 std::optional<LIBRARY_TABLE_ROW*> GetRow( LIBRARY_TABLE_TYPE aType, const wxString &aNickname,
504
505 std::optional<LIBRARY_TABLE_ROW*> FindRowByURI( LIBRARY_TABLE_TYPE aType, const wxString &aUri,
507
509 void ReloadLibraryEntry( LIBRARY_TABLE_TYPE aType, const wxString& aNickname,
511
514 std::optional<LIB_STATUS> LoadLibraryEntry( LIBRARY_TABLE_TYPE aType,
515 const wxString& aNickname );
516
517 void LoadProjectTables( const wxString& aProjectPath,
518 std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
519
529 std::optional<wxString> GetFullURI( LIBRARY_TABLE_TYPE aType, const wxString& aNickname,
530 bool aSubstituted = false );
531
532 static wxString GetFullURI( const LIBRARY_TABLE_ROW* aRow, bool aSubstituted = false,
533 const PROJECT* aProject = nullptr );
534
535 static wxString ExpandURI( const wxString& aShortURI, const PROJECT& aProject );
536
537 static bool UrisAreEquivalent( const wxString& aURI1, const wxString& aURI2 );
538
550 static bool IsPcmManagedRow( const LIBRARY_TABLE_ROW& aRow );
551
555 void ApplyLibOverrides( LIBRARY_TABLE& aTable );
556
565 void SetLibOverride( const wxString& aTablePath, const wxString& aNickname,
566 bool aDisabled, bool aHidden );
567
569 void ClearLibOverride( const wxString& aTablePath, const wxString& aNickname );
570
571private:
572 void loadTables( const wxString& aTablePath, LIBRARY_TABLE_SCOPE aScope,
573 std::vector<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
574
575 void loadNestedTables( LIBRARY_TABLE& aTable );
576
578 void applyLibOverrides( LIBRARY_TABLE& aTable );
579
580 static wxString tableFileName( LIBRARY_TABLE_TYPE aType );
581
582 void createEmptyTable( LIBRARY_TABLE_TYPE aType, LIBRARY_TABLE_SCOPE aScope );
583
584 const PROJECT* const m_project;
585 std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_TABLE>> m_tables;
586
588 std::map<wxString, std::unique_ptr<LIBRARY_TABLE>> m_childTables;
589
590 // TODO: support multiple projects
591 std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_TABLE>> m_projectTables;
592
593 std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_MANAGER_ADAPTER>> m_adapters;
594
595 mutable std::mutex m_adaptersMutex;
596
597 typedef std::tuple<LIBRARY_TABLE_TYPE, LIBRARY_TABLE_SCOPE, wxString> ROW_CACHE_KEY;
598
599 std::map<ROW_CACHE_KEY, LIBRARY_TABLE_ROW*> m_rowCache;
600 mutable std::mutex m_rowCacheMutex;
601};
602
603#endif //LIBRARY_MANAGER_H
The interface used by the classes that actually can load IO plugins for the different parts of KiCad ...
virtual std::optional< LIB_STATUS > LoadOne(LIB_DATA *aLib)=0
bool loadQueuedRow(const LOAD_WORK &aWork)
Loads one queued library on a worker thread.
std::atomic_bool m_cancelling
Set with m_abort by an abort that cancels, so only such an abort turns a failed load into INVALID.
virtual std::shared_mutex & globalLibsMutex() const =0
void stopRefreshThreads(std::map< wxString, LIB_DATA > &aLibs, std::shared_mutex &aMutex, const std::function< bool(const wxString &aNickname, const LIB_DATA &aLib)> &aRetiring={})
Stops the refresh threads of the plugins in aLibs that aRetiring selects, or of all of them when it i...
std::pair< wxString, LIBRARY_TABLE_SCOPE > LOADING_KEY
std::optional< LIBRARY_TABLE * > ProjectTable() const
Retrieves the project library table for this adapter type, or nullopt if one doesn't exist.
virtual void enumerateLibrary(LIB_DATA *aLib, const wxString &aUri)=0
Override in derived class to perform library-specific enumeration.
LIBRARY_TABLE * GlobalTable() const
Retrieves the global library table for this adapter type.
virtual std::shared_mutex & globalLibsMutex()=0
std::atomic< unsigned > m_abortGeneration
Counts cancelling aborts, so a load can tell one that began after it started from one that already en...
void evictOwnedGlobalEntries()
Erases this adapter's own entries (LIB_DATA::global_owner == this) from the process-wide globalLibs()...
LIBRARY_MANAGER_ADAPTER(LIBRARY_MANAGER &aManager)
Constructs a type-specific adapter into the library manager.
std::vector< LIBRARY_TABLE_ROW * > Rows(LIBRARY_TABLE_SCOPE aScope=LIBRARY_TABLE_SCOPE::BOTH, bool aIncludeInvalid=false) const
Like LIBRARY_MANAGER::Rows but filtered to the LIBRARY_TABLE_TYPE of this adapter.
std::optional< LIBRARY_TABLE_ROW * > FindRowByURI(const wxString &aUri, LIBRARY_TABLE_SCOPE aScope=LIBRARY_TABLE_SCOPE::BOTH) const
Like LIBRARY_MANAGER::FindRowByURI but filtered to the LIBRARY_TABLE_TYPE of this adapter.
wxString getUri(const LIBRARY_TABLE_ROW *aRow) const
virtual std::map< wxString, LIB_DATA > & globalLibs()=0
void cancelLoadingPlugins(const std::vector< LOADING_KEY > &aSnapshot)
Asks the plugins in aSnapshot to end their load early, so abortLoad() does not wait out their waits.
virtual LIBRARY_TABLE_TYPE Type() const =0
The type of library table this adapter works with.
void retireAllLibraries()
For derived destructors, while globalLibs() is still resolvable and plugin worker threads can still c...
bool DeleteLibrary(const wxString &aNickname)
Deletes the given library from disk if it exists; returns true if deleted.
void asyncLoadLocked()
The body of AsyncLoad(), run with m_loadMutex already held by the caller.
LIBRARY_RESULT< LIB_DATA * > loadIfNeeded(const wxString &aNickname)
Fetches a loaded library, triggering a load of that library if it isn't loaded yet.
std::optional< wxString > FindLibraryByURI(const wxString &aURI) const
std::mutex m_loadingMutex
Libraries an async worker is enumerating, so a cancel reaches exactly those plugins.
virtual bool SupportsConfigurationDialog(const LIBRARY_TABLE_ROW &aRow) const
Configuration works from the row itself, so libraries that failed to load or are not yet committed to...
std::vector< LOADING_KEY > loadingSnapshot()
The libraries an async worker is enumerating right now.
LIB_DATA & queuedRowEntry(const LOAD_WORK &aWork)
The cache entry of a queued library, created and owned by this adapter when it is missing,...
std::shared_mutex m_librariesMutex
std::set< LOADING_KEY > m_loading
LIBRARY_MANAGER & Manager() const
std::optional< wxString > GetLibraryDescription(const wxString &aNickname) const
virtual LIBRARY_RESULT< IO_BASE * > createPlugin(const LIBRARY_TABLE_ROW *row)=0
Creates a concrete plugin for the given row.
void GlobalTablesChanged(std::initializer_list< LIBRARY_TABLE_TYPE > aChangedTables={})
Notify the adapter that the global library tables have changed.
bool HasLibrary(const wxString &aNickname, bool aCheckEnabled=false) const
Test for the existence of aNickname in the library tables.
std::optional< LIBRARY_TABLE_ROW * > GetRow(const wxString &aNickname, LIBRARY_TABLE_SCOPE aScope=LIBRARY_TABLE_SCOPE::BOTH) const
Like LIBRARY_MANAGER::GetRow but filtered to the LIBRARY_TABLE_TYPE of this adapter.
std::map< wxString, LIB_DATA > m_libraries
virtual IO_BASE * plugin(const LIB_DATA *aRow)=0
std::vector< wxString > GetLibraryNames() const
Returns a list of library nicknames that are available (skips any that failed to load)
LIBRARY_RESULT< LIB_DATA * > loadFromScope(const wxString &aNickname, LIBRARY_TABLE_SCOPE aScope, std::map< wxString, LIB_DATA > &aTarget, std::shared_mutex &aMutex)
virtual std::optional< LIB_STATUS > CheckLibrary(LIB_DATA *aLib)
Validates that a library is loadable. May not necessarily load the library!
std::vector< std::future< void > > m_futures
void withPlugin(const LOADING_KEY &aKey, const std::function< void(IO_BASE &)> &aAction)
Runs aAction on the plugin of a library when it is still in the map.
static std::recursive_mutex & pluginMutex(const wxString &aNickname)
Serializes access to a library's shared plugin instance so its single mutable cache is not raced by c...
std::shared_mutex & scopeMutex(LIBRARY_TABLE_SCOPE aScope)
virtual int ShowConfigurationDialog(const LIBRARY_TABLE_ROW &aRow, LIBRARY_TABLE_SCOPE aScope, wxWindow *aParent)
Shows the plugin's configuration dialog for a library table row.
void resumeLoadingPlugins(const std::vector< LOADING_KEY > &aCancelled)
Tells the plugins cancelLoadingPlugins() reached that the loads they were asked to end have ended.
std::atomic< size_t > m_loadTotal
virtual std::map< wxString, LIB_DATA > & globalLibs() const =0
std::atomic< size_t > m_loadCount
LIBRARY_MANAGER & m_manager
bool m_rearmPending
Set when a cancelling abort cut a worker short, and cleared only by an AsyncLoad() that starts.
std::optional< const LIB_DATA * > fetchIfLoaded(const wxString &aNickname) const
static wxString StockTableTokenizedURI(LIBRARY_TABLE_TYPE aType)
const PROJECT *const m_project
std::mutex m_rowCacheMutex
std::map< wxString, std::unique_ptr< LIBRARY_TABLE > > m_childTables
Map of full URI to table object for tables that are referenced by global or project tables.
std::map< ROW_CACHE_KEY, LIBRARY_TABLE_ROW * > m_rowCache
const PROJECT & Project() const
std::mutex m_adaptersMutex
static wxString DefaultGlobalTablePath(LIBRARY_TABLE_TYPE aType)
static std::vector< LIBRARY_TABLE_TYPE > InvalidGlobalTables()
static bool GlobalTablesValid()
std::map< LIBRARY_TABLE_TYPE, std::unique_ptr< LIBRARY_TABLE > > m_projectTables
LIBRARY_MANAGER(const LIBRARY_MANAGER &)=delete
bool IsProjectScoped() const
static bool CreateGlobalTable(LIBRARY_TABLE_TYPE aType, bool aPopulateDefaultLibraries)
void LoadGlobalTables(std::initializer_list< LIBRARY_TABLE_TYPE > aTablesToLoad={})
(Re)loads the global library tables in the given list, or all tables if no list is given
std::map< LIBRARY_TABLE_TYPE, std::unique_ptr< LIBRARY_TABLE > > m_tables
LIBRARY_MANAGER & operator=(const LIBRARY_MANAGER &)=delete
std::tuple< LIBRARY_TABLE_TYPE, LIBRARY_TABLE_SCOPE, wxString > ROW_CACHE_KEY
static wxString StockTableReferenceURI(LIBRARY_TABLE_TYPE aType)
static wxString StockTablePath(LIBRARY_TABLE_TYPE aType)
static bool IsTableValid(const wxString &aPath)
LIBRARY_MANAGER(const PROJECT *aProject=nullptr)
An explicit project is borrowed until this manager and its adapters are destroyed.
std::map< LIBRARY_TABLE_TYPE, std::unique_ptr< LIBRARY_MANAGER_ADAPTER > > m_adapters
A progress reporter interface for use in multi-threaded environments.
Container for project specific data.
Definition project.h:63
void ProjectChanged() override
#define KICOMMON_API
Definition kicommon.h:27
LOAD_STATUS
Status of a library load managed by a library adapter.
tl::expected< ResultType, LIBRARY_ERROR > LIBRARY_RESULT
LIBRARY_TABLE_TYPE
LIBRARY_TABLE_SCOPE
A library queued by AsyncLoad(), with its URI resolved on the calling thread.
Storage for an actual loaded library (including library content owned by the plugin)
std::vector< wxString > available_fields_cache
LIB_STATUS status
std::unique_ptr< IO_BASE > plugin
Never destroyed while holding the map's mutex; a plugin's worker thread may be blocked on it.
const LIBRARY_MANAGER_ADAPTER * global_owner
const LIBRARY_TABLE_ROW * row
The overall status of a loaded or loading library.
std::optional< LIBRARY_ERROR > error
LOAD_STATUS load_status