lsup_rdf/include/environment.h

/** @file environment.h
 *
 * @brief Handle LSUP environment initialization and teardown.
 */

#ifndef _LSUP_ENVIRONMENT_H
#define _LSUP_ENVIRONMENT_H

#include "store_mdb.h"


/*
 * Data types.
 */

/** @brief Environment structure containing "global" LSUP variables.
 *
 * Multiple environments may be opened within one program. One environment,
 * the default one, must always be opened before performing any operation with
 * the library.
 */
typedef struct env_t {
    LSUP_Buffer *       default_ctx;            // Default context URI.
    LSUP_MDBStore *     mdb_store;              // MDB permanent store handle.
    LSUP_MDBStore *     mdb_store_ramdisk;      // MDB RAM disk store handle.
    LSUP_NSMap *        nsm;                    // Namespace prefix map.
} LSUP_Env;


/** @brief Environment variable that gets passed around.
 */
extern LSUP_Env *LSUP_default_env;


/** @brief Initialize default context and MDB environments.
 *
 * The ramdisk data will persist after the application is shut down, but they
 * will be wiped clean the next time this function is called.
 */
LSUP_Env *
LSUP_env_new (
        const char *default_ctx, const char *mdb_path,
        const LSUP_NSMap *nsmap);


/** @brief Initialize the default environment.
 *
 * This must be called before using the library.
 *
 * The default environment is cleaned up automatically on exit.
 *
 * This environment should suit most cases, unless an application needs to use
 * multiple environments and call #LSUP_env_init with specific handles. Such
 * other environment(s) must be freed up manually with #LSUP_env_done().
 */
LSUP_rc
LSUP_init (void);


/** @brief Close an environment.
 *
 * This only needs to be done for non-default environments. The environment
 * handle is not freed.
 */
void
LSUP_env_free (LSUP_Env *env);

/** @brief Close the defailt environment.
 *
 * This is called by atexit(). If called before then, subsequent calls have
 * no effect.
 */
void LSUP_done (void);

LSUP_rc
LSUP_env_push_id (LSUP_Env *env, const uint32_t key, const char *data);

const char *
LSUP_env_get_id (LSUP_Env *env, const uint32_t key);

#endif /* _LSUP_ENVIRONMENT_H */