folkslinux
/
rpm
mirror of https://github.com/rpm-software-management/rpm.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
rpm/rpmio/rpmstrpool.h

124 lines
3.9 KiB
C
Raw Normal View History

First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
#ifndef _RPMSTRPOOL_H
#define _RPMSTRPOOL_H
add short summaries to headers that miss one
2014-05-11 08:27:26 +08:00
/** \ingroup rpmstrpool
* \file rpmio/rpmstrpool.h
*
* String pools manipulation helper functions
*
*/
Move string pool typedefs to rpmtypes.h - I suspect these will be used widely, to avoid having to include rpmstrpool.h all over in headers...
2012-09-07 19:09:35 +08:00
#include <rpm/rpmtypes.h>
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
#ifdef __cplusplus
extern "C" {
#endif
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Create a new, empty string pool.
* @return new string pool
*/
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
rpmstrPool rpmstrPoolCreate(void);
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Free a string pool and its contents. While other references exist,
* this only decrements the reference count.
* @param pool string pool
* @return NULL always
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
rpmstrPool rpmstrPoolFree(rpmstrPool pool);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Reference a string pool
* @param pool string pool
* @return new string pool reference
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
rpmstrPool rpmstrPoolLink(rpmstrPool pool);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Freeze a string pool: new strings cannot be added to a frozen pool.
* If keephash is 0, memory usage is minimized but string -> id lookups
* are no longer possible and unfreezing is an expensive operation.
* Id -> string lookups are always possible on a frozen pool too.
* @param pool string pool
* @param keephash should string -> id hash be kept around?
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
void rpmstrPoolFreeze(rpmstrPool pool, int keephash);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Unfreeze a string pool to allow new additions again.
* If keephash was not specified on freezing, this requires rehashing
* the entire pool contents.
* @param pool string pool
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
void rpmstrPoolUnfreeze(rpmstrPool pool);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Look up the id of a string. If create is specified the string is
* added to the pool if it does not already exist. Creation can only
* fail if the pool is in frozen state.
* @param pool string pool
* @param s \0-terminated string to look up
* @param create should an id be created if not already present?
* @return id of the string or 0 for not found
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
rpmsid rpmstrPoolId(rpmstrPool pool, const char *s, int create);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Look up the id of a string with predetermined length. The string does
* not have to be \0-terminated. If create is specified the string is
* added to the pool if it does not already exist. Creation can only
* fail if the pool is in frozen state.
* @param pool string pool
* @param s string to look up
* @param slen number of characters from s to consider
* @param create should an id be created if not already present?
* @return id of the string or 0 for not found
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
rpmsid rpmstrPoolIdn(rpmstrPool pool, const char *s, size_t slen, int create);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Look up a string by its pool id.
* @param pool string pool
* @param sid pool id of a string
* @return pointer to the string or NULL for invalid id
*/
Fixup string pool prototype argument names to match implementation - Just a simple s/sidpool/pool/ to match the implementation, "sidpool" is a leftover from early draft version that somehow made its way to the master tree.
2012-09-27 17:18:39 +08:00
const char * rpmstrPoolStr(rpmstrPool pool, rpmsid sid);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Return length of a string by its pool id. The result is equal to
Drop the end-of-chunk dummy entries from string pool - As pointed out by Michael Schroeder in http://lists.rpm.org/pipermail/rpm-maint/2013-September/003605.html, the dummy entries used for optimizing rpmstrPoolStrlen() are problematic in number of ways: - Walking the id's in a pool is unreliable, and rehashing can cause bogus empty strings to be added to a pool where they otherwise do not exist - rpmstrPoolNumStr() is not accurate when more than one chunk is in use - Unfortunately this means giving up the rpmstrPoolStrlen() optimization, for now at least.
2013-12-02 16:45:33 +08:00
* calling strlen() on a string retrieved through rpmstrPoolStr(), but
* the pool might be able to optimize the calculation.
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
* @param pool string pool
* @param sid pool id of a string
Drop the end-of-chunk dummy entries from string pool - As pointed out by Michael Schroeder in http://lists.rpm.org/pipermail/rpm-maint/2013-September/003605.html, the dummy entries used for optimizing rpmstrPoolStrlen() are problematic in number of ways: - Walking the id's in a pool is unreliable, and rehashing can cause bogus empty strings to be added to a pool where they otherwise do not exist - rpmstrPoolNumStr() is not accurate when more than one chunk is in use - Unfortunately this means giving up the rpmstrPoolStrlen() optimization, for now at least.
2013-12-02 16:45:33 +08:00
* @return length of the string, 0 for invalid pool or id
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
*/
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
size_t rpmstrPoolStrlen(rpmstrPool pool, rpmsid sid);
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Compare two strings for equality by their ids. The result is equal to
* calling rstreq() on two strings retrieved through rpmstrPoolStr() but
* when the id's are within the same pool, this runs in constant time.
* @param poolA string pool of the first string
* @param sidA pool id of the first string
* @param poolB string pool of the second string
* @param sidB pool id of the second string
* @return 1 if strings are equal, 0 otherwise
*/
Add a string equality check function to string pool API - As a special case, two strings (ids) from the same pool can be tested for equality in constant time (integer comparison). If the pools differ, a regular string comparison is needed.
2012-09-13 13:48:56 +08:00
int rpmstrPoolStreq(rpmstrPool poolA, rpmsid sidA,
rpmstrPool poolB, rpmsid sidB);
Add doxygen documentation to string pool API
2012-09-27 18:11:03 +08:00
/** \ingroup rpmstrpool
* Return the number of strings stored in the pool. This number is
* also the highest legal id for the pool.
* @param pool string pool
* @return number of strings in the pool
*/
Add function to get number of unique strings in the pool
2012-09-26 13:34:40 +08:00
rpmsid rpmstrPoolNumStr(rpmstrPool pool);
First cut of a libsolv-style string <-> id pool API - The pool stores "arbitrary" number of strings in a space-efficient manner, with near constant (hashed) string -> id lookup/store and constant time id -> string and id -> string length lookups. - Credits for the idea go to the Suse developers working on libsolv, the basic concept is directly lifted from there but details differ due to using rpm's own hash table implementation etc. Another minor difference is using size_t for offsets to permit over 4GB total data size on 64bit systems, the total number of id's in the pool is limited to uint32 max however (like in libsolv). - Any (re)implementation bugs by yours truly, this is almost certainly going to need further tuning and tweaking, API and otherwise.
2012-09-07 15:33:22 +08:00
#ifdef __cplusplus
}
#endif
#endif /* _RPMSIDPOOL_H */