Main Page | Data Structures | Directories | File List | Data Fields | Globals

Sadie_Index.h File Reference

A general application data-storage interface for tclSadie. More...

#include "project_utilities.h"

Go to the source code of this file.

Defines

#define SADIE_INDEX_H   1
 The standard guard against including the same header twice.

Typedefs

typedef Sad_doclistsad_doclistp_t
 An opaque pointer to the complete top level document (image) list.

Functions

void dispose_doclist (sad_doclistp_t thedoclist)
 Tear down a complete hash table.
sad_doclistp_t make_doclist (int logsize)
 Create a new empty hash table.
int sad_dispose_doc (sad_doclistp_t doclist, const char *dkey)
 Explicitly delete a top-level entry from the table.
int sad_put_doc (sad_doclistp_t doclist, const char *dkey, int logpsize, const IMAGE *img)
 Insert a new top-level entry into the table.
int sad_put_doc_property (sad_doclistp_t doclist, const char *dkey, const char *pkey, sad_property_data_destructor_t destruct, void *data)
 Add a new lower-level entry (property) to a existing top-level table entry.
void * sad_get_doc_property (const sad_doclistp_t doclist, const char *dkey, const char *pkey)
 Given a hash table, a top-level entry key, and a sub-key, recover some data.

Variables

BEGIN_C_DECLARATIONS typedef
void(* 
sad_property_data_destructor_t )(void *)
 Prototype for the data destructor callbacks associated with properties.


Detailed Description

A general application data-storage interface for tclSadie.

In addition to various global data structures dedicated to specific purposes, tclSadie uses a generalized extensible storage mechanism following a two-level hierarchy, with the top-level entities (documents or images) containing lower level properties. We hide all the implementation details behind opaque pointers (for example, the sad_doclistp_t pointers), presenting just the interface defined here to the rest of the application.

Author:
University of Arizona Digital Image Analysis Lab
Date:
1999, 2004
Version:
Id
Sadie_Index.h,v 1.1 2005/03/22 20:18:37 mmunro Exp

Definition in file Sadie_Index.h.


Function Documentation

void dispose_doclist sad_doclistp_t  thedoclist  ) 
 

Tear down a complete hash table.

We iterate through the entire table, reclaiming storage at all levels, but can't reset the pointer to it to NULL.

Parameters:
[in,out] thedoclist points to the hash table to be destroyed.

Definition at line 241 of file Sadie_Index.c.

References Sad_doclist::buckets, Sad_doclist::lock, Sad_doclist::log2nbuckets, logerr_assert, LOGERR_DEBUG, LOGERR_FUNC, Sad_docitem::next, and POSIX_THREADS.

Referenced by tclsadie_demolish_hashtable().

sad_doclistp_t make_doclist int  logsize  ) 
 

Create a new empty hash table.

If we're in a multi-threaded environment we not only allocate storage for the table, but also initialize the lock used to serialize all accesses to it.

Parameters:
[in] logsize allocate 2^logsize hash buckets.
Returns:
A pointer to the successfully created table, or NULL on failure.

Definition at line 369 of file Sadie_Index.c.

References Sad_doclist::buckets, Sad_doclist::lock, Sad_doclist::log2nbuckets, LOGERR_FUNC, and POSIX_THREADS.

Referenced by Tcl_AppInit().

int sad_dispose_doc sad_doclistp_t  doclist,
const char *  dkey
 

Explicitly delete a top-level entry from the table.

Given a hash table and the string key to one of the top-level entries, delete the entry, its data, and any of the lower level entries (properties). If locking is supported, we try to lock the entire hash table during the deletion.

Parameters:
[in,out] doclist points to the hash table.
[in] dkey points to the key for the entry to be deleted.
Returns:
Zero on success, an error code on failure.

Definition at line 596 of file Sadie_Index.c.

References logerr_assert, LOGERR_CRIT, LOGERR_DEBUG, LOGERR_ERR, LOGERR_FUNC, Sad_docitem::next, and POSIX_THREADS.

Referenced by Sadie_General_CloseCmd().

void* sad_get_doc_property const sad_doclistp_t  doclist,
const char *  dkey,
const char *  pkey
 

Given a hash table, a top-level entry key, and a sub-key, recover some data.

The hash table is organized in two levels. We use the first key to find a top-level entry (generally representing the document or image), then use a second key to search the sub-table within it (generally its properties) and return the associated data (property value). If locking is supported, we try to lock the entire hash table during the retrieval.

Parameters:
[in] doclist points to the hash table.
[in] dkey the key for the existing top-level item.
[in] pkey the key string for the new sub-entry (property name).
Returns:
An opaque pointer to the data on success, NULL on failure.

Definition at line 842 of file Sadie_Index.c.

References Sad_property::data, Sad_docitem::key, logerr_assert, LOGERR_CRIT, LOGERR_DEBUG, LOGERR_FUNC, Sad_docitem::next, and POSIX_THREADS.

Referenced by CREATE_ROI(), Sadie_Classify_LvlSliceCmd(), Sadie_Classify_MaxLikeCmd(), and Sadie_Classify_MinDistCmd().

int sad_put_doc sad_doclistp_t  doclist,
const char *  dkey,
int  logpsize,
const IMAGE *  img
 

Insert a new top-level entry into the table.

Given a table and a key string, we search for an existing entry with the same key. If it exists, we delete it (and all its lower-level entries), replacing it with a new empty entry. If it does not exist, we insert a new empty entry at the appropriate place. We use an FNV hash code to pick the initial hash bucket within which to search, then use ordinary string comparisons to match keys within the ordered list of entries within the bucket. If locking is supported, we try to lock the entire hash table during the insertion.

Parameters:
[out] doclist points to the hash table.
[in] dkey points to the key for the new item.
[in] logpsize allocate a sub-table of 2^logpsize buckets in the item.
[in] img the SADIE image associated with the top-level entry.
Returns:
Zero on success, an error code on failure.

Definition at line 514 of file Sadie_Index.c.

References Sad_doclist::buckets, Sad_doclist::lock, Sad_doclist::log2nbuckets, logerr_assert, LOGERR_CRIT, LOGERR_DEBUG, LOGERR_FUNC, Sad_docitem::next, and POSIX_THREADS.

Referenced by Sadie_General_IndexImageCmd().

int sad_put_doc_property sad_doclistp_t  doclist,
const char *  dkey,
const char *  pkey,
sad_property_data_destructor_t  destruct,
void *  data
 

Add a new lower-level entry (property) to a existing top-level table entry.

Given a table and a key string, we search for an existing entry with the same key. When found, we search beneath it for a second sub-key (property name). If this exists, we replace it with a new property, otherwise we insert the new entry at the appropriate place, including the key, data (property value), and data destructor function. Both searches use an FNV hash code to pick the initial hash bucket, then use ordinary string comparisons to match keys within the ordered list of entries within the buckets. If locking is supported, we try to lock the entire hash table during the insertion.

Parameters:
[in,out] doclist points to the hash table.
[in] dkey the key for the existing top-level item.
[in] pkey the key string for the new sub-entry (property name).
[in] destruct a destructor function for the data we're adding.
[in] data is an opaque pointer to the sub-item data (property value).
Returns:
Zero on success, an error code on failure.

Definition at line 765 of file Sadie_Index.c.

References Sad_docitem::key, logerr_assert, LOGERR_CRIT, LOGERR_DEBUG, LOGERR_FUNC, make_property(), Sad_docitem::next, and POSIX_THREADS.

Referenced by CREATE_ROI().


Generated on Fri Jul 8 14:55:02 2005 for tclSadie by  doxygen 1.4.2