persisted.h

/* Jazz (c) 2018-2026 kaalam.ai (The Authors of Jazz), using (under the same license):
 
    1. Biomodelling - The AATBlockQueue class (c) Jacques Basaldúa, 2009-2012 licensed
      exclusively for the use in the Jazz server software.
 
      Copyright 2009-2012 Jacques Basaldúa
 
    2. BBVA - Jazz: A lightweight analytical web server for data-driven applications.
 
      Copyright 2016-2017 Banco Bilbao Vizcaya Argentaria, S.A.
 
      This product includes software developed at
 
      BBVA (https://www.bbva.com/)
 
    3. LMDB, Copyright 2011-2017 Howard Chu, Symas Corp. All rights reserved.
 
      Licensed under http://www.OpenLDAP.org/license.html
 
 
      Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
      http://www.apache.org/licenses/LICENSE-2.0
 
      Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
*/
 
 
#include "src/jazz_elements/volatile.h"
 
#ifdef CATCH_TEST
#ifndef INCLUDED_JAZZ_CATCH2
#define INCLUDED_JAZZ_CATCH2
 
#include "src/catch2/catch.hpp"
 
#endif
#endif
 
 
#ifndef INCLUDED_JAZZ_ELEMENTS_PERSISTED
#define INCLUDED_JAZZ_ELEMENTS_PERSISTED
 
#include "src/lmdb/lmdb.h"
 
 
namespace jazz_elements
{
 
#define MAX_POSSIBLE_SOURCES                32              
#define MAX_LMDB_HOME_LEN                  128              
#define LMDB_UNIX_FILE_PERMISSIONS        0664              
#define INVALID_MDB_DBI             0xefefEFEF              
 
 
// Bit masks to trigger LMDB failures in Persisted wrappers during tests.
#define TRIGGER_FAIL_MDB_ENV_CREATE         (1u << 0)       
#define TRIGGER_FAIL_MDB_ENV_SET_MAXREADERS (1u << 1)       
#define TRIGGER_FAIL_MDB_ENV_SET_MAXDBS     (1u << 2)       
#define TRIGGER_FAIL_MDB_ENV_SET_MAPSIZE    (1u << 3)       
#define TRIGGER_FAIL_MDB_ENV_OPEN           (1u << 4)       
#define TRIGGER_FAIL_MDB_ENV_SYNC           (1u << 5)       
#define TRIGGER_FAIL_MDB_TXN_BEGIN          (1u << 6)       
#define TRIGGER_FAIL_MDB_DBI_OPEN           (1u << 7)       
#define TRIGGER_FAIL_MDB_PUT                (1u << 8)       
#define TRIGGER_FAIL_MDB_TXN_COMMIT         (1u << 9)       
#define TRIGGER_FAIL_MDB_DEL                (1u << 10)      
#define TRIGGER_FAIL_MDB_GET                (1u << 11)      
#define TRIGGER_FAIL_MDB_CURSOR_OPEN        (1u << 12)      
#define TRIGGER_FAIL_MDB_CURSOR_GET         (1u << 13)      
#define TRIGGER_FAIL_MDB_DROP               (1u << 14)      
 
 
struct JazzLmdbOptions {
    char path[MAX_LMDB_HOME_LEN];           
 
    int env_set_mapsize;                    
    int env_set_maxreaders;                 
    int env_set_maxdbs;                     
    int flags;                              
};
 
 
typedef std::map <String, MDB_dbi> DBImap;  
typedef MDB_txn *pMDB_txn;                  
 
 
class Persisted : public Container {
 
    public:
 
        Persisted(pLogger a_logger, pConfigFile a_config);
       ~Persisted();
 
        virtual pChar const id();
 
        StatusCode start    ();
        StatusCode shut_down();
 
        // The easy interface (Requires explicit pulling because of the native interface using the same names.)
 
        using Container::get;
        using Container::header;
        using Container::put;
        using Container::new_entity;
        using Container::remove;
        using Container::copy;
 
        // The "native" interface
 
        virtual StatusCode get       (pTransaction      &p_txn,
                                      Locator           &what);
        virtual StatusCode get       (pTransaction      &p_txn,
                                      Locator           &what,
                                      pBlock             p_row_filter);
        virtual StatusCode get       (pTransaction      &p_txn,
                                      Locator           &what,
                                      pChar              name);
        virtual StatusCode header    (StaticBlockHeader &hea,
                                      Locator           &what);
        virtual StatusCode header    (pTransaction      &p_txn,
                                      Locator           &what);
        virtual StatusCode put       (Locator           &where,
                                      pBlock             p_block,
                                      int                mode = WRITE_AS_FULL_BLOCK);
        virtual StatusCode new_entity(Locator           &where);
        virtual StatusCode remove    (Locator           &where);
        virtual StatusCode copy      (Locator           &where,
                                      Locator           &what);
 
        // Support for container names in the BaseAPI .base_names()
 
        void base_names(BaseNames &base_names);
        bool dbi_exists(Name       dbi_name);
 
        inline bool is_running() {
            return lmdb_env != nullptr;
        }
 
#ifndef CATCH_TEST
    private:
#endif
 
        // Hot LMDB get
 
        pBlock lock_pointer_to_block(Locator &what, pMDB_txn &p_txn);
        void   done_pointer_to_block(pMDB_txn &p_txn);
 
        // Internal dbi management
 
        bool open_all_databases ();
        void close_all_databases();
        StatusCode new_database   (pChar name);
        StatusCode remove_database(pChar name);
 
        // Logger with full messages for lmdb errors.
 
        void log_lmdb_err(int loglevel, int lmdb_err, const char *msg);
 
#ifdef CATCH_TEST
        // LMDB wrappers for tests, allowing deterministic failure injection.
        int mdb_env_create         (MDB_env **env);
        int mdb_env_set_maxreaders (MDB_env *env,
                                    unsigned int readers);
        int mdb_env_set_maxdbs     (MDB_env *env,
                                    MDB_dbi dbs);
        int mdb_env_set_mapsize    (MDB_env *env,
                                    mdb_size_t size);
        int mdb_env_open           (MDB_env *env,
                                    const char *path,
                                    unsigned int flags,
                                    mdb_mode_t mode);
        int mdb_env_sync           (MDB_env *env,
                                    int force);
        int mdb_txn_begin          (MDB_env *env,
                                    MDB_txn *parent,
                                    unsigned int flags,
                                    MDB_txn **txn);
        int mdb_dbi_open           (MDB_txn *txn,
                                    const char *name,
                                    unsigned int flags,
                                    MDB_dbi *dbi);
        int mdb_put                (MDB_txn *txn,
                                    MDB_dbi dbi,
                                    MDB_val *key,
                                    MDB_val *data,
                                    unsigned int flags);
        int mdb_txn_commit         (MDB_txn *txn);
        int mdb_del                (MDB_txn *txn,
                                    MDB_dbi dbi,
                                    MDB_val *key,
                                    MDB_val *data);
        int mdb_get                (MDB_txn *txn,
                                    MDB_dbi dbi,
                                    MDB_val *key,
                                    MDB_val *data);
        int mdb_cursor_open        (MDB_txn *txn,
                                    MDB_dbi dbi,
                                    MDB_cursor **cursor);
        int mdb_cursor_get         (MDB_cursor *cursor,
                                    MDB_val *key,
                                    MDB_val *data,
                                    MDB_cursor_op op);
        int mdb_drop               (MDB_txn *txn,
                                    MDB_dbi dbi,
                                    int del);
 
        uint32_t debug_trigger_failure = 0;
#endif
 
        DBImap           source_dbi = {};       
        JazzLmdbOptions  lmdb_opt;              
        MDB_env         *lmdb_env = nullptr;    
};
typedef Persisted *pPersisted;                  
 
// Instancing Persisted
// --------------------
 
#ifdef CATCH_TEST
 
extern Persisted PER;
 
#endif
 
} // namespace jazz_elements
 
#endif // ifndef INCLUDED_JAZZ_ELEMENTS_PERSISTED