openmpi/opal/mca/dstore/dstore.h

/*
 * Copyright (c) 2010      Cisco Systems, Inc.  All rights reserved. 
 * Copyright (c) 2012-2013 Los Alamos National Security, Inc.  All rights reserved.
 * Copyright (c) 2013-2014 Intel, Inc. All rights reserved.
 * $COPYRIGHT$
 * 
 * Additional copyrights may follow
 * 
 * $HEADER$
 */
/** @file:
 *
 * The Database Framework - used for internal storage of
 * information relating to modex and other OMPI operations
 *
 */

#ifndef OPAL_DB_H
#define OPAL_DB_H

#include "opal_config.h"
#include "opal/types.h"

#include "opal/mca/mca.h"
#include "opal/mca/event/event.h"
#include "opal/dss/dss_types.h"
#include "opal/util/proc.h"

#include "opal/mca/dstore/dstore_types.h"

/**
 * DATABASE DESIGN
 *
 * Each API function is treated as blocking.
 * 
 */

BEGIN_C_DECLS

/* declare a global handle until such time
 * as someone figures out how to separate the various
 * datastore channels
 */
OPAL_DECLSPEC extern int opal_dstore_internal;
OPAL_DECLSPEC extern int opal_dstore_modex;

OPAL_DECLSPEC extern int opal_dstore_peer;
OPAL_DECLSPEC extern int opal_dstore_internal;
OPAL_DECLSPEC extern int opal_dstore_nonpeer;

/****    DEFINE THE PUBLIC API'S    ****/
/*
 * Open a database
 * 
 * Open a database for access. The name field is purely for
 * debug purposes and has no implementation relevance.
 * Just like the standard POSIX file open, the call will return
 * a unique "handle" that must be provided with any subsequent
 * call to store or fetch data from this database.
 *
 * The attributes parameter can be used to pass any desired
 * optional directives to the active storage component. These
 * are passed as a list of opal_value_t's.
 *
 * NOTE: calls to these APIs must be thread-protected as there
 * is NO internal thread safety.
 */
typedef int (*opal_dstore_base_API_open_fn_t)(const char *name,  char* desired_components,
                                              opal_list_t *attributes);

/*
 * Update an existing handle
 *
 * Sometimes an existing handle requires an update to its attributes, so
 * provide an API for doing so
 */
typedef int (*opal_dstore_base_API_update_fn_t)(int dstorehandle,
                                                opal_list_t *attributes);

/*
 * Close a database handle
 *
 * Close the specified database handle. A -1 handle indicates
 * that ALL open database handles are to be closed.
 */
typedef int (*opal_dstore_base_API_close_fn_t)(int dstorehandle);

/*
 * Store a data value against the primary key  - overwrites any data
 * of matching key that is already present. The data is copied into the database
 * and therefore does not need to be preserved by the caller.
 */
typedef int (*opal_dstore_base_API_store_fn_t)(int dstorehandle,
                                               const opal_process_name_t *id,
                                               opal_value_t *kv);

/*
 * Retrieve data
 *
 * Retrieve data for the given primary key associated with the specified key. Wildcards
 * are supported here as well. Caller is responsible for releasing the returned list
 * of opal_value_t objects.
 */
typedef int (*opal_dstore_base_API_fetch_fn_t)(int dstorehandle,
                                               const opal_process_name_t *id,
                                               const char *key,
                                               opal_list_t *kvs);

/*
 * Delete data
 *
 * Delete the data for the given primary key that is associated with the specified key.
 * If a NULL key is provided, all data for the given primary key will be deleted.
 */
typedef int (*opal_dstore_base_API_remove_fn_t)(int dstorehandle,
                                                const opal_process_name_t *id,
                                                const char *key);


/*
 * Get active dstore handle
 * Get dstore handle asocciated with the passed id.
 */
typedef int (*opal_dstore_base_API_get_handle_fn_t)(int dstorehandle, void **dhdl);


/*
 * the standard public API data structure
 */
typedef struct {
    opal_dstore_base_API_open_fn_t           open;
    opal_dstore_base_API_update_fn_t         update;
    opal_dstore_base_API_close_fn_t          close;
    opal_dstore_base_API_store_fn_t          store;
    opal_dstore_base_API_fetch_fn_t          fetch;
    opal_dstore_base_API_remove_fn_t         remove;
    opal_dstore_base_API_get_handle_fn_t     get_handle;
} opal_dstore_base_API_t;



/****    DEFINE THE MODULE API'S    ****/
/* Note that each datastore handle will be associated with
 * a single active module. Thus, storing and fetching data
 * from that module does not require that we pass in the
 * handle itself.
 *
 * NOTE: the call to actually store/fetch data in a given
 * datastore handle must be protected against threaded operations
 * as there is NO thread protection inside the various modules.
 */
struct opal_dstore_base_module_t;

/*
 * Initialize the module
 */
typedef int (*opal_dstore_base_module_init_fn_t)(struct opal_dstore_base_module_t *mod);

/*
 * Finalize the module
 */
typedef void (*opal_dstore_base_module_finalize_fn_t)(struct opal_dstore_base_module_t *mod);

/* store the data in this module */
typedef int (*opal_dstore_base_module_store_fn_t)(struct opal_dstore_base_module_t *mod,
                                                  const opal_process_name_t *id,
                                                  opal_value_t *kv);

/* fetch data from the module */
typedef int (*opal_dstore_base_module_fetch_fn_t)(struct opal_dstore_base_module_t *mod,
                                                  const opal_process_name_t *id,
                                                  const char *key,
                                                  opal_list_t *kvs);

/* remove data */
typedef int (*opal_dstore_base_module_remove_fn_t)(struct opal_dstore_base_module_t *mod,
                                                   const opal_process_name_t *id,
                                                   const char *key);

/*
 * the standard module data structure
 */
typedef struct {
    opal_dstore_base_module_init_fn_t            init;
    opal_dstore_base_module_finalize_fn_t        finalize;
    opal_dstore_base_module_store_fn_t           store;
    opal_dstore_base_module_fetch_fn_t           fetch;
    opal_dstore_base_module_remove_fn_t          remove;
} opal_dstore_base_module_t;

/*
 * the component data structure
 */

/* create and return a datastore module */
typedef opal_dstore_base_module_t* (*mca_dstore_base_component_create_hdl_fn_t)(opal_list_t *attributes);

/* update an existing handle */
typedef int (*mca_dstore_base_component_update_hdl_fn_t)(int hdl, opal_list_t *attributes);

/* provide a chance for the component to finalize */
typedef void (*mca_dstore_base_component_finalize_fn_t)(void);

typedef struct {
    mca_base_component_t                      base_version;
    mca_base_component_data_t                 base_data;
    mca_dstore_base_component_create_hdl_fn_t create_handle;
    mca_dstore_base_component_update_hdl_fn_t update_handle;
    mca_dstore_base_component_finalize_fn_t   finalize;
} opal_dstore_base_component_t;

/*
 * Macro for use in components that are of type dstore
 */
#define OPAL_DSTORE_BASE_VERSION_2_0_0 \
  MCA_BASE_VERSION_2_0_0, \
  "dstore", 2, 0, 0

/* Global structure for accessing store functions */
OPAL_DECLSPEC extern opal_dstore_base_API_t opal_dstore;  /* holds base function pointers */

END_C_DECLS

#endif