/** \ingroup dbprim_link
* \brief Dynamically initialize a linked list element.
*
* This function dynamically initializes a linked list element.
*
* \param elem A pointer to a #link_elem_t to be initialized.
* \param object
* A pointer to \c void used to represent the object
* associated with the element. May not be \c NULL.
*
* \retval DB_ERR_BADARGS A \c NULL pointer was passed for \p
* elem or \p object.
*/
unsigned long
le_init(link_elem_t *elem, void *object)
{
initialize_dbpr_error_table(); /* initialize error table */
if (!elem || !object) /* verify arguments */
return DB_ERR_BADARGS;
elem->le_next = 0; /* initialize the element */
elem->le_prev = 0;
elem->le_object = object;
elem->le_head = 0;
elem->le_flags = 0;
elem->le_magic = LINK_ELEM_MAGIC; /* set the magic number */
return 0;
}
/** ingroup dbprim_smat
* \brief Flush a row or column of a sparse matrix.
*
* This function flushes a sparse matrix row or column--that is, it
* removes each element from that row or column. If a \p flush_func
* is specified, it will be called on the entry after it has been
* removed from the row or column, and may safely call
* <CODE>free()</CODE>.
*
* \param list A pointer to a #smat_head_t.
* \param flush_func
* A pointer to a callback function used to perform
* user-specifed actions on an entry after removing it
* from the row or column. May be \c NULL. See the
* documentation for #smat_iter_t for more information.
* \param extra A \c void pointer that will be passed to \p
* flush_func.
*
* \retval DB_ERR_BADARGS An argument was invalid.
*/
unsigned long
sh_flush(smat_head_t *head, smat_iter_t flush_func, void *extra)
{
struct _sh_flush_s sf;
initialize_dbpr_error_table(); /* initialize error table */
if (!sh_verify(head)) /* verify arguments */
return DB_ERR_BADARGS;
/* initialize extra data... */
sf.sf_table = head->sh_table;
sf.sf_elem = head->sh_elem;
sf.sf_flush = flush_func;
sf.sf_extra = extra;
/* call into linked list library to flush the list */
return ll_flush(&head->sh_head, _sh_flush_iter, &sf);
}
/** \ingroup dbprim_hash
* \brief Move an entry in the hash table.
*
* This function moves an existing entry in the hash table to
* correspond to the new key.
*
* \param table A pointer to a #hash_table_t.
* \param entry A pointer to a #hash_entry_t to be moved. It must
* already be in the hash table.
* \param key A pointer to a #db_key_t describing the new key for
* the entry.
*
* \retval DB_ERR_BADARGS An invalid argument was given.
* \retval DB_ERR_UNUSED Entry is not in a hash table.
* \retval DB_ERR_WRONGTABLE Entry is not in this hash table.
* \retval DB_ERR_FROZEN Hash table is frozen.
* \retval DB_ERR_DUPLICATE New key is a duplicate of an existing
* key.
* \retval DB_ERR_READDFAILED Unable to re-add entry to table.
*/
unsigned long
ht_move(hash_table_t *table, hash_entry_t *entry, db_key_t *key)
{
unsigned long retval;
initialize_dbpr_error_table(); /* initialize error table */
if (!ht_verify(table) || !he_verify(entry) || !key) /* verify arguments */
return DB_ERR_BADARGS;
if (!entry->he_table) /* it's not in a table */
return DB_ERR_UNUSED;
if (entry->he_table != table) /* it's in the wrong table */
return DB_ERR_WRONGTABLE;
if (table->ht_flags & HASH_FLAG_FREEZE) /* don't mess with frozen tables */
return DB_ERR_FROZEN;
if (!ht_find(table, 0, key)) /* don't permit duplicates */
return DB_ERR_DUPLICATE;
/* remove the entry from the table */
if ((retval = ll_remove(&table->ht_table[entry->he_hash], &entry->he_elem)))
return retval;
/* rekey the entry */
entry->he_key = *key; /* thank goodness for structure copy! */
/* get the new hash value for the entry */
entry->he_hash =
(*table->ht_func)(table, &entry->he_key) % table->ht_modulus;
/* Now re-add it to the table */
if ((retval = ll_add(&table->ht_table[entry->he_hash], &entry->he_elem,
LINK_LOC_HEAD, 0))) {
table->ht_count--; /* decrement the count--don't worry about shrinking */
entry->he_table = 0; /* zero the table pointer */
return DB_ERR_READDFAILED;
}
return 0;
}
/** \ingroup dbprim_smat
* \brief Remove an entry from a sparse matrix.
*
* This function removes the given entry from the specified sparse
* matrix.
*
* \param table A pointer to a #smat_table_t.
* \param entry A pointer to a #smat_entry_t to be removed from the
* table.
*
* \retval DB_ERR_BADARGS An invalid argument was given.
* \retval DB_ERR_WRONGTABLE Entry is not in this sparse matrix.
* \retval DB_ERR_UNRECOVERABLE An unrecoverable error occurred while
* removing the entry from the table.
*/
unsigned long
st_remove(smat_table_t *table, smat_entry_t *entry)
{
initialize_dbpr_error_table(); /* initialize error table */
/* verify arguments */
if (!st_verify(table) || !se_verify(entry))
return DB_ERR_BADARGS;
/* verify entry is in this table */
if (entry->se_table != table)
return DB_ERR_WRONGTABLE;
/* remove the entry from the linked lists and from the hash table */
if (_st_remove(table, entry, (ST_REM_HASH | ST_REM_FIRST | ST_REM_SECOND |
ST_REM_FREE)))
return DB_ERR_UNRECOVERABLE;
return 0;
}
/** \ingroup dbprim_smat
* \brief Dynamically initialize a sparse matrix row or column head.
*
* This function dynamically initializes a sparse matrix row or column
* linked list head. The \p elem argument specifies whether the
* object is to be associated with a #SMAT_LOC_FIRST list or a
* #SMAT_LOC_SECOND list.
*
* \param head A pointer to a #smat_head_t to be initialized.
* \param elem Either #SMAT_LOC_FIRST or #SMAT_LOC_SECOND.
* \param object
* A pointer to the object containing the sparse matrix
* row or column head.
*
* \retval DB_ERR_BADARGS An invalid argument was given.
*/
unsigned long
sh_init(smat_head_t *head, smat_loc_t elem, void *object)
{
unsigned long retval;
initialize_dbpr_error_table(); /* initialize error table */
/* verify arguments... */
if (!head || (elem != SMAT_LOC_FIRST && elem != SMAT_LOC_SECOND))
return DB_ERR_BADARGS;
/* initialize list head */
if ((retval = ll_init(&head->sh_head, object)))
return retval;
head->sh_elem = elem; /* initialize list head */
head->sh_table = 0;
head->sh_magic = SMAT_HEAD_MAGIC; /* set magic number */
return 0;
}
/** \ingroup dbprim_link
* \brief Flush a linked list.
*
* This function flushes a linked list--that is, it removes each
* element from the list. If a \p flush_func is specified, it will be
* called on the entry after it has been removed from the list, and
* may safely call <CODE>free()</CODE>.
*
* \param list A pointer to a #link_head_t.
* \param flush_func
* A pointer to a callback function used to perform
* user-specified actions on an element after removing it
* from the list. May be \c NULL. See the documentation
* for #link_iter_t for more information.
* \param extra A \c void pointer that will be passed to \p
* flush_func.
*
* \retval DB_ERR_BADARGS An argument was invalid.
*/
unsigned long
ll_flush(link_head_t *list, link_iter_t flush_func, void *extra)
{
link_elem_t *elem;
unsigned long retval;
initialize_dbpr_error_table(); /* initialize error table */
if (!ll_verify(list)) /* Verify arguments */
return DB_ERR_BADARGS;
while ((elem = list->lh_first)) { /* Walk through the list... */
ll_remove(list, elem); /* remove the element */
/* call flush function, erroring out if it fails */
if (flush_func && (retval = (*flush_func)(list, elem, extra)))
return retval;
}
list->lh_count = 0; /* clear the list head */
list->lh_first = 0;
list->lh_last = 0;
return 0;
}
