2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
6 * This software is available to you under a choice of one of two
7 * licenses. You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials
23 * provided with the distribution.
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
41 * Declaration of the DB interface.
44 #include <complib/cl_list.h>
45 #include <complib/cl_spinlock.h>
46 #include <opensm/osm_log.h>
49 # define BEGIN_C_DECLS extern "C" {
50 # define END_C_DECLS }
51 #else /* !__cplusplus */
52 # define BEGIN_C_DECLS
54 #endif /* __cplusplus */
57 /****h* OpenSM/Database
62 * The OpenSM database interface provide the means to restore persistent
63 * data, query, modify, delete and eventually commit it back to the
66 * The interface is defined such that it can is not "data dependent":
67 * All keys and data items are texts.
69 * The DB implementation should be thread safe, thus callers do not need to
70 * provide serialization.
72 * This object should be treated as opaque and should be
73 * manipulated only through the provided functions.
76 * Eitan Zahavi, Mellanox Technologies LTD
79 /****s* OpenSM: Database/osm_db_domain_t
84 * A domain of the database. Can be viewed as a database table.
86 * The osm_db_domain_t object should be treated as opaque and should
87 * be manipulated only through the provided functions.
91 typedef struct osm_db_domain {
98 * Pointer to the parent database object.
101 * Pointer to the db implementation object
107 /****s* OpenSM: Database/osm_db_t
112 * The main database object.
114 * The osm_db_t object should be treated as opaque and should
115 * be manipulated only through the provided functions.
119 typedef struct osm_db {
127 * Pointer to the database implementation object
130 * Pointer to the OSM logging facility
133 * List of initialize domains
138 /****f* OpenSM: Database/osm_db_construct
143 * Construct a database.
147 void osm_db_construct(IN osm_db_t * const p_db);
151 * [in] Pointer to the database object to construct
157 * Database, osm_db_init, osm_db_destroy
160 /****f* OpenSM: Database/osm_db_destroy
165 * Destroys the osm_db_t structure.
169 void osm_db_destroy(IN osm_db_t * const p_db);
173 * [in] Pointer to osm_db_t structure to destroy
176 * Database, osm_db_construct, osm_db_init
179 /****f* OpenSM: Database/osm_db_init
184 * Initializes the osm_db_t structure.
188 int osm_db_init(IN osm_db_t * const p_db, IN osm_log_t * p_log);
193 * [in] Pointer to the database object to initialize
196 * [in] Pointer to the OSM logging facility
199 * 0 on success 1 otherwise
202 * Database, osm_db_construct, osm_db_destroy
205 /****f* OpenSM: Database/osm_db_domain_init
210 * Initializes the osm_db_domain_t structure.
214 osm_db_domain_t *osm_db_domain_init(IN osm_db_t * const p_db,
215 IN char *domain_name);
220 * [in] Pointer to the database object to initialize
223 * [in] a char array with the domain name.
226 * pointer to the new domain object or NULL if failed.
229 * Database, osm_db_construct, osm_db_destroy
232 /****f* OpenSM: Database/osm_db_restore
237 * Reads the entire domain from persistent storage - overrides all
238 * existing cached data (if any).
242 int osm_db_restore(IN osm_db_domain_t * p_domain);
247 * [in] Pointer to the database domain object to restore
251 * 0 if successful 1 otherwize
254 * Database, osm_db_domain_init, osm_db_clear, osm_db_store,
255 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
258 /****f* OpenSM: Database/osm_db_clear
263 * Clears the entire domain values from/in the cache
267 int osm_db_clear(IN osm_db_domain_t * p_domain);
272 * [in] Pointer to the database domain object to clear
275 * 0 if successful 1 otherwize
278 * Database, osm_db_domain_init, osm_db_restore, osm_db_store,
279 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
282 /****f* OpenSM: Database/osm_db_store
287 * Store the domain cache back to the database (commit)
291 int osm_db_store(IN osm_db_domain_t * p_domain);
296 * [in] Pointer to the database domain object to restore from
300 * 0 if successful 1 otherwize
303 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear,
304 * osm_db_keys, osm_db_lookup, osm_db_update, osm_db_delete
307 /****f* OpenSM: Database/osm_db_keys
312 * Retrive all keys of the domain
316 int osm_db_keys(IN osm_db_domain_t * p_domain, OUT cl_list_t * p_key_list);
321 * [in] Pointer to the database domain object
324 * [out] List of key values. It should be PRE constructed and initialized.
327 * 0 if successful 1 otherwize
329 * NOTE: the caller needs to free and destruct the list,
330 * the keys returned are intrnal to the hash and should NOT be free'ed
333 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
334 * osm_db_lookup, osm_db_update, osm_db_delete
337 /****f* OpenSM: Database/osm_db_lookup
342 * Lookup an entry in the domain by the given key
346 /* lookup value by key */
347 char *osm_db_lookup(IN osm_db_domain_t * p_domain, IN char *const p_key);
352 * [in] Pointer to the database domain object
355 * [in] The key to look for
358 * the value as char * or NULL if not found
361 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
362 * osm_db_keys, osm_db_update, osm_db_delete
365 /****f* OpenSM: Database/osm_db_update
370 * Set the value of the given key
375 osm_db_update(IN osm_db_domain_t * p_domain,
376 IN char *const p_key, IN char *const p_val);
381 * [in] Pointer to the database domain object
384 * [in] The key to update
387 * [in] The value to update
392 * NOTE: the value will be duplicated so can be free'ed
395 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
396 * osm_db_keys, osm_db_lookup, osm_db_delete
399 /****f* OpenSM: Database/osm_db_delete
404 * Delete an entry by the given key
408 int osm_db_delete(IN osm_db_domain_t * p_domain, IN char *const p_key);
413 * [in] Pointer to the database domain object
416 * [in] The key to look for
422 * Database, osm_db_domain_init, osm_db_restore, osm_db_clear, osm_db_store,
423 * osm_db_keys, osm_db_lookup, osm_db_update
427 #endif /* _OSM_DB_H_ */