Associative stores in ESF are a convenience data structure used for a wide range of purposes, such as retrieving ESM text configuration items and tracking named objects (locks and memory areas) in non-CAS environments.
An associative store is an associative array with a two-part key: a class (which is a namespace, in effect) and a name. The value is an object pointer of any type; the caller is expected to know the type. Note that the data pointed to by the pointer is not stored in the array - storing it is the caller's responsibility. Class and name are stored verbatim but compared case-insensitively.
Stores are implemented with a hash table for the class data. The name data is not currently indexed, but is hashed for fast probablistic comparisons. (A full comparison is done on a match to prevent false positives, of course.)
Stores support adding and removing values, looking up a specific value, and iterating through values.
The code here is based on code taken from MFCS's store.c 1.3.
Definition in file saf-store.c.
Go to the source code of this file.
Defines | |
| #define | SafINI_MAX_LINE 260 |
| #define | SafINI_MAX_TAG 160 |
| #define | SafINI_MAX_NAME 80 |
| #define | SafINI_MAX_VALUE 160 |
Functions | |
| SafRet | SafAllocStore (struct SafStore **StoreP) |
| Create a store. | |
| SafRet | SafFreeStore (struct SafStore *Store) |
| Free a store and the class and name data in it. | |
| SafRet | SafClearStore (struct SafStore *Store) |
| Remove all the data from a store. | |
| SafRet | SafStoreRemove (struct SafStore *Store, const char *Class, const char *Name) |
| Remove an entry from a store. | |
| SafRet | SafStoreIterate (struct SafStore *Store, const char *Class, SafRet(*Visitor)(const char *Class, const char *Name, void *Value, void *Data), void *Data, SafRet *VisitorErrP) |
| Iterate over a store, optionally filtering for a single class. | |
| SafRet | SafStoreAdd (struct SafStore *Store, const char *Class, const char *Name, void *Pointer) |
| Add an entry to a store. | |
| SafRet | SafStoreFind (struct SafStore *Store, const char *Class, const char *Name, void **PointerP) |
| Retrieve an entry from a store. | |
| SafRet | SafStoreLoad (struct SafStore *Store, const char *Text) |
| Load a store from structured text. | |
| SafRet SafAllocStore | ( | struct SafStore ** | StoreP | ) |
Create a store.
A factory for associative stores. The caller defines a variable of type "pointer to struct SafStore" (an opaque structure) and passes its address to SafAllocStore:
struct SafStore *MyStore = NULL; SafRet Ret; Ret = SafAllocStore(&MyStore); if (Ret) // handle error...
| [out] | StoreP | Pointer to a pointer to a struct SafStore which will receive the address of the newly-created store. |
Definition at line 610 of file saf-store.c.
References SafIsMT(), SafR_OK, SafR_PARAM, and SafR_RESOURCE.
Referenced by EsmParseConfig().
| SafRet SafFreeStore | ( | struct SafStore * | Store | ) |
Free a store and the class and name data in it.
Free a store, including freeing the internal data structures and the class and name data. The store must not be used after this function has been called.
| [in] | Store | The store to be freed. |
Definition at line 671 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
Referenced by EsmParseConfig().
| SafRet SafClearStore | ( | struct SafStore * | Store | ) |
Remove all the data from a store.
Free the data in a store and reset it to its pristine state without reallocating or freeing the store itself or its mutex. This allows a store to be safely cleaned out while it may be in use by other threads.
| [in] | Store | The store to be cleared. |
Definition at line 735 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
| SafRet SafStoreRemove | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name | |||
| ) |
Remove an entry from a store.
| [in] | Store | The store |
| [in] | Class | Class of the value to be removed |
| [in] | Name | Name of the value to be removed |
Definition at line 804 of file saf-store.c.
References SafR_PARAM.
Referenced by SafStoreLoad().
| SafRet SafStoreIterate | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| SafRet(*)(const char *Class, const char *Name, void *Value, void *Data) | Visitor, | |||
| void * | Data, | |||
| SafRet * | VisitorErrP | |||
| ) |
Iterate over a store, optionally filtering for a single class.
Iterate through the given store, calling the supplied visitor function on each value. Optionally filter by class. A nonzero return from the visitor ends iteration.
| [in] | Store | The store |
| [in] | Class | An optional class name to restrict the iteration to values belonging to the specified class |
| [in] | Visitor | A callback, invoked for each value |
| [in] | Data | An optional pointer which will be passed to the visitor callback |
| [out] | VisitorErrP | Returns the final error code of the visitor callback |
Definition at line 850 of file saf-store.c.
References SafR_NOMORE, SafR_OK, SafR_PARAM, and SafSTRCMP_CI.
| SafRet SafStoreAdd | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name, | |||
| void * | Pointer | |||
| ) |
Add an entry to a store.
Add an entry to a store using the given class and name. The class and name strings are duplicated (and need not be preserved by the caller). The contents of the pointer being stored are not inspected; they are the caller's responsibility. If a value with the same class and name already exists in the store, it will be silently replaced.
| [in] | Store | The store |
| [in] | Class | Class to store the value under |
| [in] | Name | Name of the value |
| [in] | Pointer | Pointer to be stored |
Definition at line 927 of file saf-store.c.
References SafDupStr(), SafR_NOTFOUND, SafR_OK, SafR_PARAM, and SafR_RESOURCE.
Referenced by SafStoreLoad().
| SafRet SafStoreFind | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name, | |||
| void ** | PointerP | |||
| ) |
Retrieve an entry from a store.
Locate the entry in the given store with the given class and name, and set the output PointerP parameter to its value.
| [in] | Store | The store |
| [in] | Class | Class of the value to be located |
| [in] | Name | Name of the value to be located |
| [out] | PointerP | Returns the pointer value from the store |
Definition at line 996 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
Referenced by EsmQueryConfig(), and SafQueryCfg().
| SafRet SafStoreLoad | ( | struct SafStore * | Store, | |
| const char * | Text | |||
| ) |
Load a store from structured text.
Parse a string in "ini"-format structured text format, and add entries to a store corresponding to the sections, names, and values contained in it.
The format has name=value pairs, one per line, within sections indicated by a name in square brackets on a separate line (sometimes called a "section tag"). Blank lines and lines beginning with the comment character ; are ignored, and leading and trailing whitespace is removed from names and values.
For example:
[Section One] Alice=1 Bob=2 # A comment [Section Two] Path = /some/series/of/directories a list = apples bananas pears #This = is commented out true = 1=1
The store provided by the caller (which must have been initialized, but need not be empty) will be populated with entries as follows: the section name string (again, leading and trailing whitespace removed) becomes the class for each section, names are entry names, and values are copied into individually-allocated string buffers that become the values in the store entries.
Any name-value pairs that appear before the first section tag will be stored under an empty class (a class of "").
So, given the sample data above:
struct SafStore *Config; extern const char *ConfigData; // points to string shown above void *Bob; // Parse the data into the store SafAllocStore(&Config); SafStoreLoad(Config, ConfigData); // Get value of "Bob" in "Section One" SafStoreFind(Config, "section one", "Bob", &Bob); printf("Bob is %s\n", Bob);
| [out] | Store | The store to update from the parsed text |
| [in] | Text | The ini-format text to be parsed |
Definition at line 1096 of file saf-store.c.
References SafDupStr(), SafR_INVALID, SafR_OK, SafR_PARAM, SafR_RESOURCE, SafStoreAdd(), SafStoreRemove(), and SafSTRING.
Referenced by EsmParseConfig().