lmdbal/src/base.cpp

/*
 * LMDB Abstraction Layer.
 * Copyright (C) 2023  Yury Gubich <blue@macaw.me>
 *
 * 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 <http://www.gnu.org/licenses/>.
 */

#include "base.h"
#include "exceptions.h"
#include "session.h"
#include "storage.h"
#include "transaction.h"
#include "session.h"

#define UNUSED(x) (void)(x)

/**
 * \class LMDBAL::Base
 * \brief Database abstraction
 *
 * This is a basic class that represents the database as a collection of storages.
 * Storages are something that key-value databases have instead of tables in classic SQL databases.
 */

/**
 * \brief Creates the database
 *
 * \param[in] _name      -   name of the database, it is going to affect the folder name that is created to store data
 * \param[in] _mapSize   -   LMDB map size (MiB), multiplied by 1024^2 and passed to <a class="el" href="http://www.lmdb.tech/doc/group__mdb.html#gaa2506ec8dab3d969b0e609cd82e619e5">mdb_env_set_mapsize</a> during the call of LMDBAL::Base::open()
 */
LMDBAL::Base::Base(const QString& _name, uint16_t _mapSize):
    name(_name.toStdString()),
    sessions(),
    size(_mapSize),
    environment(),
    storages(),
    transactions(),
    mutex()
{}

/**
 * \brief Destroys the database
 */
LMDBAL::Base::~Base() {
    std::lock_guard lock(mutex);

    for (Session* session : sessions)
        session->terminate();

    if (opened())
        deactivate();

    for (const std::pair<const std::string, StorageCommon*>& pair : storages)
        delete pair.second;
}

LMDBAL::Session LMDBAL::Base::open() {
    return {this};
}


/**
 * \brief Removes database directory
 *
 * \returns true if removal was successful of if no directory was created where it's expected to be, false otherwise
 *
 * \exception LMDBAL::Opened   - thrown if this function was called on an opened database
 */
bool LMDBAL::Base::removeDirectory() {
    if (opened())
        throw Opened(name, "remove database directory");

    QString path = getPath();
    QDir cache(path);

    if (cache.exists())
        return cache.removeRecursively();
    else
        return true;
}

/**
 * \brief Creates database directory
 *
 * Creates or opens existing directory with the given name in the location acquired with
 * <a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html">QStandardPaths</a>::<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html#writableLocation">writableLocation</a>(<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html">QStandardPaths</a>::<a class="el" href="https://doc.qt.io/qt-6/qstandardpaths.html#StandardLocation-enum">CacheLocation</a>)
 * so, the file system destination of your data would depend on the
 * <a class="el" href="https://doc.qt.io/qt-6/qcoreapplication.html">QCoreApplication</a> configuration of your app.
 * This function does nothing if the directory was already created
 *
 * \returns the path of the created directory
 *
 * \exception LMDBAL::Opened    - thrown if called on an opened database
 * \exception LMDBAL::Directory - if the database couldn't create the folder
 */
QString LMDBAL::Base::createDirectory() {
    if (opened())
        throw Opened(name, "create database directory");

    QString path = getPath();
    QDir cache(path);
    if (!cache.exists()) {
        bool res = cache.mkpath(path);
        if (!res)
            throw Directory(path.toStdString());
    }

    return path;
}

/**
 * \brief Returns database name
 *
 * \returns database name
 */
QString LMDBAL::Base::getName() const {
    return QString::fromStdString(name);}

/**
 * \brief Returns database name
 *
 * \returns database path
 */
QString LMDBAL::Base::getPath() const {
    QString path(QStandardPaths::writableLocation(QStandardPaths::CacheLocation));
    path += "/" + getName();

    return path;
}

/**
 * \brief Returns database state
 *
 * \returns true if the database is opened and ready for work, false otherwise
 */
bool LMDBAL::Base::opened() const {
    return !sessions.empty();
}

/**
 * \brief Drops the database
 *
 * Clears all caches and storages of the database
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happend
 */
void LMDBAL::Base::drop() {
    if (!opened())
        throw Closed("drop", name);

    TransactionID txn = beginPrivateTransaction(emptyName);
    for (const std::pair<const std::string, StorageCommon*>& pair : storages) {
        int rc = pair.second->drop(txn);
        if (rc != MDB_SUCCESS) {
            abortPrivateTransaction(txn, emptyName);
            throw Unknown(name, mdb_strerror(rc), pair.first);
        }
    }

    commitPrivateTransaction(txn, emptyName);
    for (const std::pair<const std::string, StorageCommon*>& pair : storages)
        pair.second->handleDrop();
}

/**
 * \brief Begins read-only transaction
 *
 * This is the legitimate way to retrieve LMDBAL::Transaction.
 * LMDBAL::Transaction is considered runnig right after creation by this method.
 * You can terminate transaction manually calling LMDBAL::Transaction::terminate
 * but it's not required, because transaction will be terminated automatically
 * (if it was not terminated manually) upon the call of the destructor.
 *
 * You can not use termitated transaction any more.
 *
 * \returns read-only transaction
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::Transaction LMDBAL::Base::beginReadOnlyTransaction() const {
    TransactionID id = beginReadOnlyTransaction(emptyName);
    return Transaction(id, this);
}

/**
 * \brief Begins writable transaction
 *
 * This is the legitimate way to retrieve LMDBAL::WriteTransaction.
 * LMDBAL::WriteTransaction is considered runnig right after creation by this method.
 * You can commit all the changes made by this transaction calling LMDBAL::WriteTransaction::commit.
 * You can cancel any changes made bu this transaction calling LMDBAL::WriteTransaction::abort
 * (or LMDBAL::Transaction::terminate which LMDBAL::WriteTransaction inherits),
 * but it's not required, because transaction will be aborted automatically
 * (if it was not terminated (committed <b>OR</b> aborted) manually) upon the call of the destructor.
 *
 * You can not use termitated transaction any more.
 *
 * \returns writable transaction
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::WriteTransaction LMDBAL::Base::beginTransaction() {
    TransactionID id = beginTransaction(emptyName);
    return WriteTransaction(id, this);
}

/**
 * \brief Aborts transaction
 *
 * Terminates transaction cancelling changes.
 * Every storage receives notification about this transaction being aborted.
 * This is an optimal way to abort public transactions
 *
 * \param[in] id    - transaction ID you want to abort
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id) const {
    return abortTransaction(id, emptyName);}

/**
 * \brief Commits transaction
 *
 * Terminates transaction applying changes.
 * Every storage receives notification about this transaction being committed.
 * This is an optimal way to commit public transactions
 *
 * \param[in] id    - transaction ID you want to commit
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id) {
    return commitTransaction(id, emptyName);}

/**
 * \brief Begins read-only transaction
 *
 * This function is intended to be called from subordinate storage, cache, transaction or cursor.
 * Every storage receives notification about this transaction being started.
 * This is an optimal way to begin read-only public transactions.
 *
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \returns read-only transaction ID
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::TransactionID LMDBAL::Base::beginReadOnlyTransaction(const std::string& storageName) const {
    if (!opened())
        throw Closed("beginReadOnlyTransaction", name, storageName);

    TransactionID txn = beginPrivateReadOnlyTransaction(storageName);
    for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
        pair.second->transactionStarted(txn, true);

    return txn;
}

/**
 * \brief Begins writable transaction
 *
 * This function is intended to be called from subordinate storage, cache, transaction or cursor.
 * Every storage receives notification about this transaction being started.
 * This is an optimal way to begin public transactions.
 *
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \returns writable transaction ID
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::TransactionID LMDBAL::Base::beginTransaction(const std::string& storageName) const {
    if (!opened())
        throw Closed("beginTransaction", name, storageName);

    TransactionID txn = beginPrivateTransaction(storageName);
    for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
        pair.second->transactionStarted(txn, false);

    return txn;
}

/**
 * \brief Aborts transaction
 *
 * Terminates transaction cancelling changes.
 * Every storage receives notification about this transaction being aborted.
 * This is an optimal way to abort public transactions.
 * This function is intended to be called from subordinate storage, cache, transaction or cursor
 *
 * \param[in] id            - transaction ID you want to abort
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
void LMDBAL::Base::abortTransaction(LMDBAL::TransactionID id, const std::string& storageName) const {
    if (!opened())
        throw Closed("abortTransaction", name, storageName);

    abortPrivateTransaction(id, storageName);
    for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
        pair.second->transactionAborted(id);
}

/**
 * \brief Commits transaction
 *
 * Terminates transaction applying changes.
 * Every storage receives notification about this transaction being committed.
 * This is an optimal way to commit public transactions
 * This function is intended to be called from subordinate storage, cache, transaction or cursor
 *
 * \param[in] id            - transaction ID you want to commit
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \exception LMDBAL::Closed    - thrown if the database is closed
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
void LMDBAL::Base::commitTransaction(LMDBAL::TransactionID id, const std::string& storageName) {
    if (!opened())
        throw Closed("abortTransaction", name, storageName);

    commitPrivateTransaction(id, storageName);
    for (const std::pair<const std::string, LMDBAL::StorageCommon*>& pair : storages)
        pair.second->transactionCommited(id);
}

/**
 * \brief Begins read-only transaction
 *
 * This function is intended to be called from subordinate storage or cache,
 * it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
 *
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \returns read-only transaction ID
 *
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::TransactionID LMDBAL::Base::beginPrivateReadOnlyTransaction(const std::string& storageName) const {
    MDB_txn* txn;
    int rc = mdb_txn_begin(environment, NULL, MDB_RDONLY, &txn);
    if (rc != MDB_SUCCESS)
        throw Unknown(name, mdb_strerror(rc), storageName);

    return txn;
}

/**
 * \brief Begins writable transaction
 *
 * This function is intended to be called from subordinate storage or cache,
 * it's not accounted in the transaction collection, other storages and caches are not notified about this kind of transaction
 *
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \returns writable transaction ID
 *
 * \exception LMDBAL::Unknown   - thrown if something unexpected happened
 */
LMDBAL::TransactionID LMDBAL::Base::beginPrivateTransaction(const std::string& storageName) const {
    MDB_txn* txn;
    int rc = mdb_txn_begin(environment, NULL, 0, &txn);
    if (rc != MDB_SUCCESS) {
        mdb_txn_abort(txn);
        throw Unknown(name, mdb_strerror(rc), storageName);
    }
    return txn;
}

/**
 * \brief Aborts transaction
 *
 * Terminates transaction, cancelling changes.
 * This is an optimal way to terminate read-only transactions.
 * This function is intended to be called from subordinate storage or cache,
 * it's not accounted in the transaction collection, other storages and caches are not notified about this kind of transaction
 *
 * \param[in] id            - transaction ID you want to abort
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, unused here
 */
void LMDBAL::Base::abortPrivateTransaction(LMDBAL::TransactionID id, const std::string& storageName) const {
    UNUSED(storageName);
    mdb_txn_abort(id);
}

/**
 * \brief Commits transaction
 *
 * Terminates transaction applying changes.
 * This function is intended to be called from subordinate storage or cache
 * it's not accounted in transaction collection, other storages and caches are not notified about this kind of transaction
 *
 * \param[in] id            - transaction ID you want to commit
 * \param[in] storageName   - name of the storage/cache that you begin transaction from, needed just to inform if something went wrong
 *
 * \exception LMDBAL::Unknown   - thrown if transaction with given ID was not found or if something unexpected happened
 */
void LMDBAL::Base::commitPrivateTransaction(LMDBAL::TransactionID id, const std::string& storageName) {
    int rc = mdb_txn_commit(id);
    if (rc != MDB_SUCCESS)
        throw Unknown(name, mdb_strerror(rc), storageName);
}

/**
 * \brief Registers session
 *
 * Registers the session in the session collection.
 * If it was the first accounted session, it activates the database
 *
 * \exception LMDBAL::Unknown   - thrown if this session was already registered
 */
void LMDBAL::Base::registerSession(Session* session) {
    std::lock_guard lock(mutex);

    if (sessions.empty())
        activate();

    if (!sessions.insert(session).second)
        throw Unknown(name, "session already registered");
}

/**
 * \brief Unregisters session
 *
 * Unregisters the session from the session collection.
 * If it was the last accounted session, it deactivates the database
 *
 * \exception LMDBAL::Unknown   - thrown if this session was not registered
 */
void LMDBAL::Base::unregisterSession(Session* session) {
    std::lock_guard lock(mutex);

    if (sessions.size() == 1)
        deactivate();

    if (sessions.erase(session) != 1)
        throw Unknown(name, "session was not registered");
}

/**
 * \brief Swaps sessions
 *
 * Replaces one session by another in the session collection.
 *
 * \exception LMDBAL::Unknown   - thrown if there is some unexpected state with sessions, it means the database is in the wrong state
 */
void LMDBAL::Base::replaceSession(Session* closing, Session* opening) {
    std::lock_guard lock(mutex);

    if (sessions.erase(closing) != 1)
        throw Unknown(name, "session was not registered");

    if (!sessions.insert(opening).second)
        throw Unknown(name, "session already registered");
}

/**
 * \brief Deactivates the database,
 *
 * Closes all lmdb handles, aborts all public transactions.
 * This function will emit SIGSEGV on a deactivated database
 *
 * \exception LMDBAL::Unknown   - thrown if something went wrong aborting transactions
 */
void LMDBAL::Base::deactivate() {
    for (const std::pair<TransactionID, Transaction*> pair : transactions) {
        abortTransaction(pair.first, emptyName);
        pair.second->reset();
    }

    for (const std::pair<const std::string, StorageCommon*>& pair : storages)
        pair.second->close();

    mdb_env_close(environment);
    transactions.clear();
}

/**
 * \brief Activates the database
 *
 * Almost every LMDBAL::Base require it to be opened, this function does it.
 * It also creates the directory for the database if it was an initial launch.
 * This function will behave unpredictably on an activated database, possible data corruption.
 *
 * \exception LMDBAL::Unknown - thrown if something went wrong opening storages and caches
 */
void LMDBAL::Base::activate() {
    mdb_env_create(&environment);
    QString path = createDirectory();

    mdb_env_set_maxdbs(environment, static_cast<MDB_dbi>(storages.size()));
    mdb_env_set_mapsize(environment, size * 1024UL * 1024UL);
    mdb_env_open(environment, path.toStdString().c_str(), 0, 0664);

    TransactionID txn = beginPrivateTransaction(emptyName);
    for (const std::pair<const std::string, StorageCommon*>& pair : storages) {
        StorageCommon* storage = pair.second;
        if (const int rc = storage->open(txn))
            throw Unknown(name, mdb_strerror(rc));
    }

    commitPrivateTransaction(txn, emptyName);
}