library_manager.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 * @author Jon Evans <[email protected]>
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef LIBRARY_MANAGER_H
#define LIBRARY_MANAGER_H
 
#include <future>
#include <memory>
#include <mutex>
#include <shared_mutex>
 
#include <kicommon.h>
#include <ki_error.h>
#include <libraries/library_table.h>
#include <io/io_base.h>
 
 
class LIBRARY_MANAGER;
class LIBRARY_MANAGER_ADAPTER;
class PROJECT;
 

enum class LOAD_STATUS
{
    INVALID,
    LOADING,
    LOADED,
    LOAD_ERROR
};

struct KICOMMON_API LIB_STATUS
{
    LOAD_STATUS                  load_status = LOAD_STATUS::INVALID;
    std::optional<LIBRARY_ERROR> error = std::nullopt;
};
 

struct KICOMMON_API LIB_DATA
{
    std::unique_ptr<IO_BASE> plugin;
    const LIBRARY_TABLE_ROW* row = nullptr;
    LIB_STATUS               status;
 
    // For an entry in the process-wide globalLibs() cache, the adapter that loaded it and so owns
    // the lifetime of row. Its destructor evicts the entry; identity is by adapter, not by the
    // reusable row pointer.
    const LIBRARY_MANAGER_ADAPTER* global_owner = nullptr;
 
    int                   modify_hash = -1;
    std::vector<wxString> available_fields_cache;
};
 

class KICOMMON_API LIBRARY_MANAGER_ADAPTER
{
public:
    LIBRARY_MANAGER_ADAPTER( LIBRARY_MANAGER& aManager );
 
    virtual ~LIBRARY_MANAGER_ADAPTER();
 
    LIBRARY_MANAGER& Manager() const;

    virtual LIBRARY_TABLE_TYPE Type() const = 0;

    LIBRARY_TABLE* GlobalTable() const;

    std::optional<LIBRARY_TABLE*> ProjectTable() const;
 
    std::optional<wxString> FindLibraryByURI( const wxString& aURI ) const;

    std::vector<wxString> GetLibraryNames() const;

    bool HasLibrary( const wxString& aNickname, bool aCheckEnabled = false ) const;

    bool DeleteLibrary( const wxString& aNickname );
 
    std::optional<wxString> GetLibraryDescription( const wxString& aNickname ) const;

    std::vector<LIBRARY_TABLE_ROW*> Rows( LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH,
                                          bool                aIncludeInvalid = false ) const;

    std::optional<LIBRARY_TABLE_ROW*> GetRow( const wxString&     aNickname,
                                              LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH ) const;

    std::optional<LIBRARY_TABLE_ROW*> FindRowByURI( const wxString&     aUri,
                                                    LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH ) const;

    virtual void ProjectChanged();

    void GlobalTablesChanged( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );

    void ProjectTablesChanged( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );

    void ProjectTablesReloaded( std::initializer_list<LIBRARY_TABLE_TYPE> aChangedTables = {} );
 
    void CheckTableRow( LIBRARY_TABLE_ROW& aRow );

    void AsyncLoad();
 
    virtual std::optional<LIB_STATUS> LoadOne( LIB_DATA* aLib ) = 0;

    virtual std::optional<LIB_STATUS> CheckLibrary( LIB_DATA* aLib ) { return LoadOne( aLib ); }

    std::optional<float> AsyncLoadProgress() const;
 
    void BlockUntilLoaded();

    void AbortAsyncLoad();
 
    bool IsLibraryLoaded( const wxString& aNickname );

    std::optional<LIB_STATUS> GetLibraryStatus( const wxString& aNickname ) const;

    std::vector<std::pair<wxString, LIB_STATUS>> GetLibraryStatuses() const;

    std::vector<KI_ERROR> GetLibraryLoadErrors() const;

    void ReloadLibraryEntry( const wxString& aNickname,
                             LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH );

    std::optional<LIB_STATUS> LoadLibraryEntry( const wxString& aNickname );

    virtual bool IsWritable( const wxString& aNickname ) const;

    bool CreateLibrary( const wxString& aNickname );

    virtual bool SupportsConfigurationDialog( const LIBRARY_TABLE_ROW& aRow ) const { return false; }

    virtual int ShowConfigurationDialog( const LIBRARY_TABLE_ROW& aRow, LIBRARY_TABLE_SCOPE aScope,
                                         wxWindow* aParent )
    {
        return wxID_CANCEL;
    }
 
    virtual std::optional<LIBRARY_ERROR> LibraryError( const wxString& aNickname ) const;
 
protected:
    virtual std::map<wxString, LIB_DATA>& globalLibs() = 0;
    virtual std::map<wxString, LIB_DATA>& globalLibs() const = 0;
    virtual std::shared_mutex&            globalLibsMutex() = 0;
    virtual std::shared_mutex&            globalLibsMutex() const = 0;

    virtual void enumerateLibrary( LIB_DATA* aLib, const wxString& aUri ) = 0;
 
    wxString getUri( const LIBRARY_TABLE_ROW* aRow ) const;
 
    std::optional<const LIB_DATA*> fetchIfLoaded( const wxString& aNickname ) const;
 
    std::optional<LIB_DATA*> fetchIfLoaded( const wxString& aNickname );

    LIBRARY_RESULT<LIB_DATA*> loadIfNeeded( const wxString& aNickname );
 
    LIBRARY_RESULT<LIB_DATA*> loadFromScope( const wxString& aNickname,
                                             LIBRARY_TABLE_SCOPE aScope,
                                             std::map<wxString, LIB_DATA>& aTarget,
                                             std::shared_mutex& aMutex );

    void evictOwnedGlobalEntries();

    void abortLoad();

    void resetProjectCache();

    virtual LIBRARY_RESULT<IO_BASE*> createPlugin( const LIBRARY_TABLE_ROW* row ) = 0;
 
    virtual IO_BASE* plugin( const LIB_DATA* aRow ) = 0;

    static std::recursive_mutex& pluginMutex( const wxString& aNickname );
 
    LIBRARY_MANAGER& m_manager;
 
    // The actual library content is held in an associated IO plugin
    std::map<wxString, LIB_DATA> m_libraries;
 
    mutable std::shared_mutex m_librariesMutex;
 
    std::atomic_bool               m_abort;
    std::vector<std::future<void>> m_futures;
 
    std::atomic<size_t> m_loadCount{ 0 };
    std::atomic<size_t> m_loadTotal{ 0 };
    std::mutex          m_loadMutex;
};
 
 
class KICOMMON_API LIBRARY_MANAGER
{
public:
    explicit LIBRARY_MANAGER( const PROJECT* aProject = nullptr );
 
    const PROJECT& Project() const;
    bool IsProjectScoped() const { return m_project != nullptr; }
 
    ~LIBRARY_MANAGER();
 
    LIBRARY_MANAGER( const LIBRARY_MANAGER& ) = delete;
    LIBRARY_MANAGER& operator=( const LIBRARY_MANAGER& ) = delete;
 
    static wxString DefaultGlobalTablePath( LIBRARY_TABLE_TYPE aType );
 
    static wxString StockTablePath( LIBRARY_TABLE_TYPE aType );

    static wxString StockTableTokenizedURI( LIBRARY_TABLE_TYPE aType );

    static wxString StockTableReferenceURI( LIBRARY_TABLE_TYPE aType );
 
    static bool IsTableValid( const wxString& aPath );

    static bool GlobalTablesValid();

    static std::vector<LIBRARY_TABLE_TYPE> InvalidGlobalTables();
 
    static bool CreateGlobalTable( LIBRARY_TABLE_TYPE aType, bool aPopulateDefaultLibraries );

    void LoadGlobalTables( std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );

    void LoadProjectTables( std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
 
    void ReloadTables( LIBRARY_TABLE_SCOPE aScope, std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );

    void ProjectChanged();

    void AbortAsyncLoads();
 
    void RegisterAdapter( LIBRARY_TABLE_TYPE aType,
                          std::unique_ptr<LIBRARY_MANAGER_ADAPTER>&& aAdapter );
 
    bool RemoveAdapter( LIBRARY_TABLE_TYPE aType, LIBRARY_MANAGER_ADAPTER* aAdapter );
 
    std::optional<LIBRARY_MANAGER_ADAPTER*> Adapter( LIBRARY_TABLE_TYPE aType ) const;

    std::optional<LIBRARY_TABLE*> Table( LIBRARY_TABLE_TYPE aType,
                                         LIBRARY_TABLE_SCOPE aScope );

    std::vector<LIBRARY_TABLE_ROW*> Rows( LIBRARY_TABLE_TYPE aType,
                                          LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH,
                                          bool aIncludeInvalid = false ) const;

    std::optional<LIBRARY_TABLE_ROW*> GetRow( LIBRARY_TABLE_TYPE aType, const wxString &aNickname,
                                              LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH );
 
    std::optional<LIBRARY_TABLE_ROW*> FindRowByURI( LIBRARY_TABLE_TYPE aType, const wxString &aUri,
                                                    LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH ) const;

    void ReloadLibraryEntry( LIBRARY_TABLE_TYPE aType, const wxString& aNickname,
                             LIBRARY_TABLE_SCOPE aScope = LIBRARY_TABLE_SCOPE::BOTH );

    std::optional<LIB_STATUS> LoadLibraryEntry( LIBRARY_TABLE_TYPE aType,
                                                const wxString& aNickname );
 
    void LoadProjectTables( const wxString& aProjectPath,
                            std::initializer_list<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );

    std::optional<wxString> GetFullURI( LIBRARY_TABLE_TYPE aType, const wxString& aNickname,
                                        bool aSubstituted = false );
 
    static wxString GetFullURI( const LIBRARY_TABLE_ROW* aRow, bool aSubstituted = false,
                               const PROJECT* aProject = nullptr );
 
    static wxString ExpandURI( const wxString& aShortURI, const PROJECT& aProject );
 
    static bool UrisAreEquivalent( const wxString& aURI1, const wxString& aURI2 );

    static bool IsPcmManagedRow( const LIBRARY_TABLE_ROW& aRow );

    void ApplyLibOverrides( LIBRARY_TABLE& aTable );

    void SetLibOverride( const wxString& aTablePath, const wxString& aNickname,
                         bool aDisabled, bool aHidden );

    void ClearLibOverride( const wxString& aTablePath, const wxString& aNickname );
 
private:
    void loadTables( const wxString& aTablePath, LIBRARY_TABLE_SCOPE aScope,
                     std::vector<LIBRARY_TABLE_TYPE> aTablesToLoad = {} );
 
    void loadNestedTables( LIBRARY_TABLE& aTable );

    void applyLibOverrides( LIBRARY_TABLE& aTable );
 
    static wxString tableFileName( LIBRARY_TABLE_TYPE aType );
 
    void createEmptyTable( LIBRARY_TABLE_TYPE aType, LIBRARY_TABLE_SCOPE aScope );
 
    const PROJECT* const m_project;
    std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_TABLE>> m_tables;

    std::map<wxString, std::unique_ptr<LIBRARY_TABLE>> m_childTables;
 
    // TODO: support multiple projects
    std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_TABLE>> m_projectTables;
 
    std::map<LIBRARY_TABLE_TYPE, std::unique_ptr<LIBRARY_MANAGER_ADAPTER>> m_adapters;
 
    mutable std::mutex m_adaptersMutex;
 
    typedef std::tuple<LIBRARY_TABLE_TYPE, LIBRARY_TABLE_SCOPE, wxString> ROW_CACHE_KEY;
 
    std::map<ROW_CACHE_KEY, LIBRARY_TABLE_ROW*> m_rowCache;
    mutable std::mutex                          m_rowCacheMutex;
};
 
#endif //LIBRARY_MANAGER_H