This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
TfHash Class Reference

A user-extensible hashing mechanism for use with runtime hash tables. More...

#include <hash.h>

Public Member Functions

template<class T >
auto operator() (T &&obj) const -> decltype(Tf_HashImpl(std::declval< Tf_HashState & >(), std::forward< T >(obj), 0), size_t())
 Produce a hash code for obj.
 

Static Public Member Functions

template<class... Args>
static size_t Combine (Args &&... args)
 Produce a hash code by combining the hash codes of several objects.
 

Detailed Description

A user-extensible hashing mechanism for use with runtime hash tables.

The hash functions here are appropriate for storing objects in runtime hash tables. They are not appropriate for document signatures / fingerprinting or for storage and offline use. No specific guarantee is made about hash function quality, and the resulting hash codes are only 64-bits wide. Callers must assume that collisions will occur and be prepared to deal with them.

Additionally, no guarantee is made about repeatability from run-to-run. That is, within a process lifetime an object's hash code will not change (provided its internal state does not change). But an object with equivalent state in a future run of the same process may hash differently.

At the time of this writing we observe good performance combined with the "avalanche" quality (~50% output bit flip probability for a single input bit flip) in the low-order 40 output bits. Higher order bits do not achieve avalanche, and the highest order 8 bits are particularly poor. But for our purposes we deem this performance/quality tradeoff acceptable.

This mechanism has builtin support for integral and floating point types, some STL types and types in Tf. TfHash uses three methods to attempt to hash a passed object. First, TfHash tries to call TfHashAppend() on its argument. This is the primary customization point for TfHash. If that is not viable, TfHash tries to call std::hash<T>{}(). Lastly, TfHash makes an unqualified call to hash_value.

The best way to add TfHash support for user-defined types is to provide a function overload like the following.

template <class HashState>
void TfHashAppend(HashState &h, MyType const &myObj)
h.Append(myObject._member1,
myObject._member2,
myObject._member3);
h.AppendContiguous(myObject._memberArray, myObject._numArrayElems);
}

The HashState object is left deliberately unspecified, so that different hash state objects may be used in different circumstances without modifying this support code, and without excess abstraction penalty. The methods available for use in TfHashAppend overloads are:

// Append several objects to the hash state. This invokes the TfHash
// mechanism so it works for any types supported by TfHash.
template <class... Args>
void HashState::Append(Args &&... args);
// Append contiguous objects to the hash state. Note that this is
// explicitly *not* guaranteed to produce the same result as calling
// Append() with each object in order.
template <class T>
void HashState::AppendContiguous(T const *objects, size_t numObjects);
// Append a general range of objects to the hash state. Note that this is
// explicitly *not* guaranteed to produce the same result as calling
// Append() with each object in order.
template <class Iter>
void AppendRange(Iter f, Iter l);

The TfHash class function object supports:

  • integral types (including bool)
  • floating point types
  • std::string
  • TfRefPtr
  • TfWeakPtr
  • TfEnum
  • const void*
  • types that provide overloads for TfHashAppend
  • types that provide overloads for std::hash
  • types that provide overloads for hash_value

The TfHash class can be used to instantiate a TfHashMap with string keys as follows:

TfHashMap<string, int, TfHash> m;
m["abc"] = 1;

TfHash()(const char*) is disallowed to avoid confusion of whether the pointer or the string is being hashed. If you want to hash a C-string use TfHashCString and if you want to hash a char* use TfHashCharPtr.

Definition at line 460 of file hash.h.

Member Function Documentation

◆ Combine()

static size_t Combine ( Args &&...  args)
inlinestatic

Produce a hash code by combining the hash codes of several objects.

Definition at line 475 of file hash.h.

◆ operator()()

auto operator() ( T &&  obj) const -> decltype(Tf_HashImpl(std::declval<Tf_HashState &>(), std::forward<T>(obj), 0), size_t())
inline

Produce a hash code for obj.

See the class documentation for details.

Definition at line 465 of file hash.h.


The documentation for this class was generated from the following file: