/*
* Copyright (c) 2004-2009 Voltaire, Inc. All rights reserved.
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
*
* This software is available to you under a choice of one of two
* licenses. You may choose to be licensed under the terms of the GNU
* General Public License (GPL) Version 2, available from the file
* COPYING in the main directory of this source tree, or the
* OpenIB.org BSD license below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*/
#ifndef _OSM_DB_H_
#define _OSM_DB_H_
/*
* Abstract:
* Declaration of the DB interface.
*/
#include <complib/cl_list.h>
#include <complib/cl_spinlock.h>
struct osm_log;
#ifdef __cplusplus
# define BEGIN_C_DECLS extern "C" {
# define END_C_DECLS }
#else /* !__cplusplus */
# define BEGIN_C_DECLS
# define END_C_DECLS
#endif /* __cplusplus */
BEGIN_C_DECLS
/****h* OpenSM/Database
* NAME
* Database
*
* DESCRIPTION
* The OpenSM database interface provide the means to restore persistent
* data, query, modify, delete and eventually commit it back to the
* persistent media.
*
* The interface is defined such that it can is not "data dependent":
* All keys and data items are texts.
*
* The DB implementation should be thread safe, thus callers do not need to
* provide serialization.
*
* This object should be treated as opaque and should be
* manipulated only through the provided functions.
*
* AUTHOR
* Eitan Zahavi, Mellanox Technologies LTD
*
*********/
/****s* OpenSM: Database/osm_db_domain_t
* NAME
* osm_db_domain_t
*
* DESCRIPTION
* A domain of the database. Can be viewed as a database table.
*
* The osm_db_domain_t object should be treated as opaque and should
* be manipulated only through the provided functions.
*
* SYNOPSIS
*/
typedef struct osm_db_domain {
struct osm_db *p_db;
void *p_domain_imp;
} osm_db_domain_t;
/*
* FIELDS
* p_db
* Pointer to the parent database object.
*
* p_domain_imp
* Pointer to the db implementation object
*
* SEE ALSO
* osm_db_t
*********/
/****s* OpenSM: Database/osm_db_t
* NAME
* osm_db_t
*
* DESCRIPTION
* The main database object.
*
* The osm_db_t object should be treated as opaque and should
* be manipulated only through the provided functions.
*
* SYNOPSIS
*/
typedef struct osm_db {
void *p_db_imp;
struct osm_log *p_log;
cl_list_t domains;
} osm_db_t;
/*
* FIELDS
* p_db_imp
* Pointer to the database implementation object
*
* p_log
* Pointer to the OSM logging facility
*
* domains
* List of initialize domains
*
* SEE ALSO
*********/
/****f* OpenSM: Database/osm_db_construct
* NAME
* osm_db_construct
*
* DESCRIPTION
* Construct a database.
*
* SYNOPSIS
*/
void osm_db_construct(IN osm_db_t * p_db);
/*
* PARAMETERS
* p_db
* [in] Pointer to the database object to construct
*
* RETURN VALUES
* NONE
*
* SEE ALSO
* Database, osm_db_init, osm_db_destroy
*********/
/****f* OpenSM: Database/osm_db_destroy
* NAME
* osm_db_destroy
*
* DESCRIPTION
* Destroys the osm_db_t structure.
*
* SYNOPSIS
*/
void osm_db_destroy(IN osm_db_t * p_db);
/*
* PARAMETERS
* p_db
* [in] Pointer to osm_db_t structure to destroy
*
* SEE ALSO
* Database, osm_db_construct, osm_db_init
*********/
/****f* OpenSM: Database/osm_db_init
* NAME
* osm_db_init
*
* DESCRIPTION
* Initializes the osm_db_t structure.
*
* SYNOPSIS
*/
int osm_db_init(IN osm_db_t * p_db, IN struct osm_log * p_log);
/*
* PARAMETERS
*
* p_db
* [in] Pointer to the database object to initialize
*
* p_log
* [in] Pointer to the OSM logging facility
*
* RETURN VALUES
* 0 on success 1 otherwise
*
* SEE ALSO
* Database, osm_db_construct, osm_db_destroy
*********/
/****f* OpenSM: Database/osm_db_domain_init
* NAME
* osm_db_domain_init
*
* DESCRIPTION
* Initializes the osm_db_domain_t structure.
*
* SYNOPSIS
*/
osm_db_domain_t *osm_db_domain_init(IN osm_db_t * p_db, IN const char *domain_name);
/*
* PARAMETERS
*
* p_db
* [in] Pointer to the database object to initialize
*
* domain_name
* [in] a char array with the domain name.
*
* RETURN VALUES
* pointer to the new domain object or NULL if failed.
*
* SEE ALSO
* Database, osm_db_construct, osm_db_destroy
*********/
/****f* OpenSM: Database/osm_db_restore
* NAME
* osm_db_restore
*
* DESCRIPTION
* Reads the entire domain from persistent storage - overrides all
* existing cached data (if any).
*
* SYNOPSIS
*/
int osm_db_restore(IN osm_db_domain_t * p_domain);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object to restore
* from persistent db
*
* RETURN VALUES
* 0 if successful 1 otherwize
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_clear, osm_db_store,
* osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_clear
* NAME
* osm_db_clear
*
* DESCRIPTION
* Clears the entire domain values from/in the cache
*
* SYNOPSIS
*/
int osm_db_clear(IN osm_db_domain_t * p_domain);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object to clear
*
* RETURN VALUES
* 0 if successful 1 otherwize
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_store,
* osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_store
* NAME
* osm_db_store
*
* DESCRIPTION
* Store the domain cache back to the database (commit)
*
* SYNOPSIS
*/
int osm_db_store(IN osm_db_domain_t * p_domain,
IN boolean_t fsync_high_avail_files);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object to restore from
* persistent db
*
* fsync_high_avail_files
* [in] Boolean that indicates whether or not to synchronize
* in-memory high availability files with storage
*
* RETURN VALUES
* 0 if successful 1 otherwize
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_clear,
* osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_keys
* NAME
* osm_db_keys
*
* DESCRIPTION
* Retrive all keys of the domain
*
* SYNOPSIS
*/
int osm_db_keys(IN osm_db_domain_t * p_domain, OUT cl_list_t * p_key_list);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object
*
* p_key_list
* [out] List of key values. It should be PRE constructed and initialized.
*
* RETURN VALUES
* 0 if successful 1 otherwize
*
* NOTE: the caller needs to free and destruct the list,
* the keys returned are intrnal to the hash and should NOT be free'ed
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
* osm_db_lookup, osm_db_update, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_lookup
* NAME
* osm_db_lookup
*
* DESCRIPTION
* Lookup an entry in the domain by the given key
*
* SYNOPSIS
*/
/* lookup value by key */
char *osm_db_lookup(IN osm_db_domain_t * p_domain, IN char *p_key);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object
*
* key
* [in] The key to look for
*
* RETURN VALUES
* the value as char * or NULL if not found
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
* osm_db_keys, osm_db_update, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_update
* NAME
* osm_db_update
*
* DESCRIPTION
* Set the value of the given key
*
* SYNOPSIS
*/
int osm_db_update(IN osm_db_domain_t * p_domain, IN char *p_key, IN char *p_val);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object
*
* p_key
* [in] The key to update
*
* p_val
* [in] The value to update
*
* RETURN VALUES
* 0 on success
*
* NOTE: the value will be duplicated so can be free'ed
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
* osm_db_keys, osm_db_lookup, osm_db_delete
*********/
/****f* OpenSM: Database/osm_db_delete
* NAME
* osm_db_delete
*
* DESCRIPTION
* Delete an entry by the given key
*
* SYNOPSIS
*/
int osm_db_delete(IN osm_db_domain_t * p_domain, IN char *p_key);
/*
* PARAMETERS
*
* p_domain
* [in] Pointer to the database domain object
*
* p_key
* [in] The key to look for
*
* RETURN VALUES
* 0 on success
*
* SEE ALSO
* Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
* osm_db_keys, osm_db_lookup, osm_db_update
*********/
END_C_DECLS
#endif /* _OSM_DB_H_ */