Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(358)

Unified Diff: doc/manual/source/hash-functions.rst

Issue 6357056: Generic hash function interface, with two implementations. (Closed)
Patch Set: Respond to review comments Created 11 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | src/core/model/hash.h » ('j') | src/core/model/hash.h » ('J')
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: doc/manual/source/hash-functions.rst
===================================================================
--- a/doc/manual/source/hash-functions.rst
+++ b/doc/manual/source/hash-functions.rst
@@ -22,20 +22,63 @@
#include "ns3/hash.h"
+ using namespace ns3;
+
char * buffer = ...
size_t buffer_size = ...
- Hash::Hash32_t buffer_hash = Hash32 ( (const char *) buffer, buffer_size);
+ uint32_t buffer_hash = Hash32 ( buffer, buffer_size);
std::string s;
+ uint32_t string_hash = Hash32 (s);
- Hash::Hash32_t s_hash = Hash32 (s);
+Equivalent functions are defined for 64-bit hash values.
-The ``Hash::Hash32_t`` type is just an ``uint32_t``, as a reminder that hash
-values are opaque.
+Incremental Hashing
+*******************
-Equivalent functions and ``Hash::Hash64_t`` type are defined for 64-bit hash
-values.
+In some situations it's useful to compute the hash of multiple buffers,
+as if they had been joined together. (For example, you might want
+the hash of a packet stream, but not want to assemble a single buffer
+with the combined contents of all the packets.)
+
+This is almost as straight-forward as the first example:
+
+ #include "ns3/hash.h"
+
+ using namespace ns3;
+
+ char * buffer;
+ size_t buffer_size;
+
+ Hasher hasher; // Use default hash function
+
+ for (<every buffer>)
+ {
+ buffer = <get next buffer>;
+ hasher (buffer, buffer_size);
+ }
+ uint32_t combined_hash = hasher.GetHash32 ();
+
+By default ``Hasher`` preserves internal state to enable incremental
+hashing. If you want to reuse a ``Hasher`` object (for example
+because it's configured with a non-default hash function), but don't
+want to add to the previously computed hash, you need to ``clear()``
+first:
+
+ hasher.clear ().GetHash32 (buffer, buffer_size);
+
+This reinitializes the internal state before hashing the buffer.
+
+
+Using an Alternative Hash Function
+**********************************
+
+The default hash function is murmur3_. FNV1a_ is also available. To specify
+the hash function explicitly, use this contructor:
+
+ Hasher hasher = Hasher ( Create<Hash::Function::Fnv1a> () );
+
Adding New Hash Function Implementations
****************************************
@@ -43,23 +86,24 @@
To add the hash function ``foo``, follow the ``hash-murmur3.h``/``.cc`` pattern:
* Create a class declaration (``.h``) and definition (``.cc``) inheriting
- from ``HashImplementation``.
+ from ``Hash::Implementation``.
* ``include`` the declaration in ``hash.h`` (at the point where
``hash-murmur3.h`` is included.
* In your own code, instantiate a ``Hash`` object via the constructor
- ``Hash (Ptr<HashImplementation> (Foo))``
+ ``Hash (Ptr<Hash::Function::Foo> ())``
If your hash function is a single function, e.g. ``hashf``, you don't
even need to create a new class derived from HashImplementation::
- Hash (Ptr<HashImplementation> (Hash32Implementation<&hashf>))
+ Hasher hasher =
+ Hasher ( Create<Hash::Function::Hash32> (&hashf) );
For this to compile, your ``hashf`` has to match one of the function pointer
signatures::
- typedef Hash::Hash32_t (*Hash32Function_ptr) (const char *, const size_t);
- typedef Hash::Hash64_t (*Hash64Function_ptr) (const char *, const size_t);
+ typedef uint32_t (*Hash32Function_ptr) (const char *, const size_t);
+ typedef uint64_t (*Hash64Function_ptr) (const char *, const size_t);
Sources for Hash Functions
« no previous file with comments | « no previous file | src/core/model/hash.h » ('j') | src/core/model/hash.h » ('J')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b