diff options
Diffstat (limited to 'dev-haskell/hashtables/metadata.xml')
| -rw-r--r-- | dev-haskell/hashtables/metadata.xml | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/dev-haskell/hashtables/metadata.xml b/dev-haskell/hashtables/metadata.xml new file mode 100644 index 000000000000..534f6dfdb278 --- /dev/null +++ b/dev-haskell/hashtables/metadata.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<pkgmetadata> + <herd>haskell</herd> + <herd>proxy-maintainers</herd> + <maintainer> + <email>haskell@gentoo.org</email> + </maintainer> + <longdescription> + This package provides a couple of different implementations of mutable hash + tables in the ST monad, as well as a typeclass abstracting their common + operations, and a set of wrappers to use the hash tables in the IO monad. + + /QUICK START/: documentation for the hash table operations is provided in the + "Data.HashTable.Class" module, and the IO wrappers (which most users will + probably prefer) are located in the "Data.HashTable.IO" module. + + This package currently contains three hash table implementations: + + 1. "Data.HashTable.ST.Basic" contains a basic open-addressing hash table + using linear probing as the collision strategy. On a pure speed basis it + should currently be the fastest available Haskell hash table + implementation for lookups, although it has a higher memory overhead + than the other tables and can suffer from long delays when the table is + resized because all of the elements in the table need to be rehashed. + + 2. "Data.HashTable.ST.Cuckoo" contains an implementation of \"cuckoo + hashing\" as introduced by Pagh and Rodler in 2001 (see + <http://en.wikipedia.org/wiki/Cuckoo_hashing>). Cuckoo hashing has + worst-case /O(1)/ lookups and can reach a high \"load factor\", in which + the table can perform acceptably well even when more than 90% full. + Randomized testing shows this implementation of cuckoo hashing to be + slightly faster on insert and slightly slower on lookup than + "Data.Hashtable.ST.Basic", while being more space efficient by about a + half-word per key-value mapping. Cuckoo hashing, like the basic hash + table implementation using linear probing, can suffer from long delays + when the table is resized. + + 3. "Data.HashTable.ST.Linear" contains a linear hash table (see + <http://en.wikipedia.org/wiki/Linear_hashing>), which trades some insert + and lookup performance for higher space efficiency and much shorter + delays when expanding the table. In most cases, benchmarks show this + table to be currently slightly faster than @Data.HashTable@ from the + Haskell base library. + + It is recommended to create a concrete type alias in your code when using this + package, i.e.: + + > import qualified Data.HashTable.IO as H + > + > type HashTable k v = H.BasicHashTable k v + > + > foo :: IO (HashTable Int Int) + > foo = do + > ht <- H.new + > H.insert ht 1 1 + > return ht + + Firstly, this makes it easy to switch to a different hash table implementation, + and secondly, using a concrete type rather than leaving your functions abstract + in the HashTable class should allow GHC to optimize away the typeclass + dictionaries. + + This package accepts a couple of different cabal flags: + + * @unsafe-tricks@, default /ON/. If this flag is enabled, we use some + unsafe GHC-specific tricks to save indirections (namely @unsafeCoerce#@ + and @reallyUnsafePtrEquality#@. These techniques rely on assumptions + about the behaviour of the GHC runtime system and, although they've been + tested and should be safe under normal conditions, are slightly + dangerous. Caveat emptor. In particular, these techniques are + incompatible with HPC code coverage reports. + + * @sse41@, default /OFF/. If this flag is enabled, we use some SSE 4.1 + instructions (see <http://en.wikipedia.org/wiki/SSE4>, first available on + Intel Core 2 processors) to speed up cache-line searches for cuckoo + hashing. + + * @bounds-checking@, default /OFF/. If this flag is enabled, array accesses + are bounds-checked. + + * @debug@, default /OFF/. If turned on, we'll rudely spew debug output to + stdout. + + * @portable@, default /OFF/. If this flag is enabled, we use only pure + Haskell code and try not to use unportable GHC extensions. Turning this + flag on forces @unsafe-tricks@ and @sse41@ /OFF/. + + This package has been tested with GHC 7.0.3, on: + + * a MacBook Pro running Snow Leopard with an Intel Core i5 processor, + running GHC 7.0.3 in 64-bit mode. + + * an Arch Linux desktop with an AMD Phenom II X4 940 quad-core processor. + + * a MacBook Pro running Snow Leopard with an Intel Core 2 Duo processor, + running GHC 6.12.3 in 32-bit mode. + + Please send bug reports to + <https://github.com/gregorycollins/hashtables/issues>. + </longdescription> + <use> + <flag name="bounds-checking">if on, use bounds-checking array accesses</flag> + <flag name="portable">if on, use only pure Haskell code and no GHC extensions.</flag> + <flag name="unsafe-tricks">turn on unsafe GHC tricks</flag> + </use> + <upstream> + <remote-id type="github">gregorycollins/hashtables</remote-id> + </upstream> +</pkgmetadata> |