A Discrete-Event Network Simulator
Manual

Hash Functions

ns-3 provides a generic interface to general purpose hash functions. In the simplest usage, the hash function returns the 32-bit or 64-bit hash of a data buffer or string. The default underlying hash function is murmur3, chosen because it has good hash function properties and offers a 64-bit version. The venerable FNV1a hash is also available.

There is a straight-forward mechanism to add (or provide at run time) alternative hash function implementations.

Basic Usage

The simplest way to get a hash value of a data buffer or string is just:

#include "ns3/hash.h"

using namespace ns3;

char * buffer = ...
size_t buffer_size = ...

uint32_t  buffer_hash = Hash32 ( buffer, buffer_size);

std::string s;
uint32_t  string_hash = Hash32 (s);

Equivalent functions are defined for 64-bit hash values.

Incremental Hashing

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

To add the hash function foo, follow the hash-murmur3.h/.cc pattern:

  • Create a class declaration (.h) and definition (.cc) inheriting from Hash::Implementation.
  • include the declaration in hash.h (at the point where hash-murmur3.h is included.
  • In your own code, instantiate a Hasher object via the constructor Hasher (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:

Hasher hasher =
  Hasher ( Create<Hash::Function::Hash32> (&hashf) );

For this to compile, your hashf has to match one of the function pointer signatures:

typedef uint32_t (*Hash32Function_ptr) (const char *, const size_t);
typedef uint64_t (*Hash64Function_ptr) (const char *, const size_t);

Sources for Hash Functions

Sources for other hash function implementations include:

Table Of Contents

Previous topic

Random Variables

Next topic

Events and Simulator

This Page