ace_backend.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.
 *
 * 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 KICAD_ACE_BACKEND_H
#define KICAD_ACE_BACKEND_H
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <vector>
 
#include <database/database_backend.h>
 
#include "db_worker_thread.h"
 

struct ACE_ENGINE_OP
{
    using CLOCK = std::chrono::steady_clock;
 
    enum class STATE
    {
        IDLE,
        WAITING,  
        ACQUIRED, 
        EXPIRED   
    };
 
    explicit ACE_ENGINE_OP( CLOCK::time_point aDeadline ) :
            deadline( aDeadline )
    {
    }

    bool Busy() const
    {
        const STATE current = state;
        return current == STATE::WAITING || current == STATE::EXPIRED;
    }
 
    const CLOCK::time_point deadline;
    std::atomic<STATE>      state{ STATE::IDLE };
};
 

class ACE_BACKEND : public DATABASE_BACKEND
{
public:
    ACE_BACKEND( std::string aPath, std::string aPassword, int aTimeoutSeconds );
 
    ~ACE_BACKEND() override;
 
    bool Connect() override;
 
    void Disconnect() override;
 
    bool IsConnected() const override { return m_connected; }
 
    bool ListTables( std::vector<std::string>& aTables ) override;
 
    std::optional<DB_TABLE_INFO> DescribeTable( const std::string& aTable ) override;
 
    bool ReadTable( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns, size_t aMaxRows,
                    std::vector<std::string>& aLabels, const DB_ROW_SINK& aSink ) override;

    bool ReadAllRows( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns,
                      std::vector<std::string>& aLabels, const DB_ROW_SINK& aSink,
                      const DB_RESTART_SINK& aRestart ) override;
 
    void BeginLoadCycle( const DB_STOP_CHECK& aStopped ) override;

    void EndLoadCycle() override;
 
    std::string GetLastError() const override { return m_lastError; }
 
    DB_FAILURE GetLastFailure() const override { return m_lastFailure; }
 
    enum class PROVIDER_STATE
    {
        AVAILABLE,
        MISSING,
        PENDING, 
        BUSY     
    };

    static PROVIDER_STATE ProviderState();

    static std::string ProviderPendingMessage();

    static std::string ProviderMissingMessage();
 
private:
    struct CYCLE_SESSION
    {
        uint64_t              id = 0;
        std::set<std::string> tables;
    };

    struct PASS_DIGEST
    {
        size_t                   rows = 0;
        uint64_t                 hash = 0;
        std::vector<std::string> labels;
 
        bool operator==( const PASS_DIGEST& aOther ) const
        {
            return rows == aOther.rows && hash == aOther.hash && labels == aOther.labels;
        }
    };

    std::optional<PASS_DIGEST> readPass( uint64_t aSession, const std::string& aSql, const std::string& aUnorderedSql,
                                         size_t aMaxRows, std::vector<std::string>& aLabels, const DB_ROW_SINK* aSink,
                                         std::optional<ACE_ENGINE_OP::CLOCK::time_point> aDeadline = std::nullopt );

    std::optional<uint64_t> freshSession( const std::string& aTable, ACE_ENGINE_OP::CLOCK::time_point aDeadline,
                                          const std::function<bool()>& aMayStart );

    bool closeSpentSessions( ACE_ENGINE_OP::CLOCK::time_point aDeadline );
 
    bool cycleStopped() const;

    bool pauseUnlessStopped( std::chrono::milliseconds aWait );
 
    void failStopped( const std::string& aTable );

    bool readVerified( const DB_TABLE_INFO& aTable, const std::vector<std::string>& aColumns,
                       std::vector<std::string>& aLabels, const DB_ROW_SINK& aSink, const DB_RESTART_SINK& aRestart );

    template <typename R>
    std::optional<R> runOnWorker( std::function<R( DB_JOB_CONTEXT& )> aJob, const DB_ROW_SINK* aSink,
                                  std::shared_ptr<ACE_ENGINE_OP>           aOp = nullptr,
                                  std::optional<std::chrono::milliseconds> aProgressBound = std::nullopt );

    void dropConnection( std::shared_ptr<ACE_ENGINE_OP> aOp = nullptr, bool aForExit = false );

    bool closeOnWorker( std::vector<uint64_t> aIds, std::shared_ptr<ACE_ENGINE_OP> aOp,
                        std::optional<std::chrono::milliseconds> aBound = std::nullopt );
 
    void fail( DB_FAILURE aFailure, std::string aError );

    std::shared_ptr<ACE_ENGINE_OP> newOp() const;

    void failCall( DB_FAILURE aFailure, std::string aMessage );

    bool requireConnection();
 
    std::string m_path;
    std::string m_password;
    int         m_timeout;

    std::shared_ptr<ACE_ENGINE_OP> m_lastOp;
 
    std::unique_ptr<DB_WORKER_THREAD> m_worker;

    uint64_t m_session = 0;

    std::wstring m_progId;

    static constexpr size_t MAX_CYCLE_SESSIONS = 2;
 
    std::vector<CYCLE_SESSION> m_cycleSessions;

    DB_STOP_CHECK m_cycleStop;

    int m_cycleDepth = 0;
 
    std::atomic<bool> m_connected{ false };
 
    std::string m_lastError;
    DB_FAILURE  m_lastFailure = DB_FAILURE::UNKNOWN;
};
 
#endif // KICAD_ACE_BACKEND_H