token.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_TF_TOKEN_H
#define PXR_BASE_TF_TOKEN_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/base/tf/api.h"
#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/hash.h"
#include "pxr/base/tf/hashset.h"
#include "pxr/base/tf/pointerAndBits.h"
 
#include <atomic>
#include <iosfwd>
#include <string>
#include <vector>
#include <set>
 
PXR_NAMESPACE_OPEN_SCOPE
 
struct TfTokenFastArbitraryLessThan;
 
class TfToken
{
public:
    enum _ImmortalTag { Immortal };
 
    constexpr TfToken() noexcept = default;
 
    TfToken(TfToken const& rhs) noexcept : _rep(rhs._rep) { _AddRef(); }
 
    TfToken(TfToken && rhs) noexcept : _rep(rhs._rep) {
        rhs._rep = TfPointerAndBits<const _Rep>();
    }
    
    TfToken& operator= (TfToken const& rhs) noexcept {
        if (&rhs != this) {
            rhs._AddRef();
            _RemoveRef();
            _rep = rhs._rep;
        }
        return *this;
    }
 
    TfToken& operator= (TfToken && rhs) noexcept {
        if (&rhs != this) {
            _RemoveRef();
            _rep = rhs._rep;
            rhs._rep = TfPointerAndBits<const _Rep>();
        }
        return *this;
    }
 
    ~TfToken() { _RemoveRef(); }
    
    //
    // This constructor involves a string hash and a lookup in the global
    // table, and so should not be done more often than necessary.  When
    // possible, create a token once and reuse it many times.
    //
    // Any content in \p s past an embedded NUL is ignored, and is not stored;
    // see the class documentation.
    TF_API explicit TfToken(std::string const& s);
    TF_API TfToken(std::string const& s, _ImmortalTag);
 
    //
    // This constructor involves a string hash and a lookup in the global
    // table, and so should not be done more often than necessary.  When
    // possible, create a token once and reuse it many times.
    TF_API explicit TfToken(char const* s);
    TF_API TfToken(char const* s, _ImmortalTag);
 
    //
    // If a token has previous been created for the given string, this
    // will return it.  Otherwise, the empty token will be returned.
    //
    // Lookup uses the same identity rule as construction, so any content in
    // \p s past an embedded NUL is ignored.
    TF_API static TfToken Find(std::string const& s);
 
    //
    // The hash is based on the token's storage identity; this is immutable
    // as long as the token is in use anywhere in the process.
    //
    inline size_t Hash() const;
 
    struct HashFunctor {
        size_t operator()(TfToken const& token) const { return token.Hash(); }
    };
 
    typedef TfHashSet<TfToken, TfToken::HashFunctor> HashSet;
    
    typedef std::set<TfToken, TfTokenFastArbitraryLessThan> Set;
    
    size_t size() const {
        _Rep const *rep = _rep.Get();
        return rep ? rep->_str.size() : 0;
    }
 
    char const* GetText() const {
        _Rep const *rep = _rep.Get();
        return rep ? rep->_str.c_str() : "";
    }
 
    char const *data() const {
        return GetText();
    }
 
    std::string const& GetString() const {
        _Rep const *rep = _rep.Get();
        return rep ? rep->_str : _GetEmptyString();
    }
 
    inline void Swap(TfToken &other) {
        std::swap(_rep, other._rep);
    }
    
    bool operator==(TfToken const& o) const {
        // Equal if pointers & bits are equal, or if just pointers are.
        return _rep.Get() == o._rep.Get();
    }
 
    bool operator!=(TfToken const& o) const {
        return !(*this == o);
    }
 
    TF_API bool operator==(std::string const& o) const;
 
    TF_API bool operator==(const char *o) const;
 
    friend bool operator==(std::string const& o, TfToken const& t) {
        return t == o;
    }
 
    friend bool operator==(const char *o, TfToken const& t) {
        return t == o;
    }
 
    bool operator!=(std::string const& o) const {
        return !(*this == o);
    }
 
    friend bool operator!=(std::string const& o, TfToken const& t)  {
        return !(t == o);
    }
 
    bool operator!=(char const* o) const {
        return !(*this == o);
    }
 
    friend bool operator!=(char const* o, TfToken const& t) {
        return !(t == o);
    }
 
    inline bool operator<(TfToken const& r) const {
        auto ll = _rep.GetLiteral(), rl = r._rep.GetLiteral();
        if (!ll || !rl) {
            // One or both are zero -- return true if ll is zero and rl is not.
            return !ll && rl;
        }
        if (ll == rl) {
            return false;
        }
        auto lrep = _rep.Get(), rrep = r._rep.Get();
        uint64_t lcc = lrep->_compareCode, rcc = rrep->_compareCode;
        return lcc < rcc || (lcc == rcc && lrep->_str < rrep->_str);
    }
 
    inline bool operator>(TfToken const& o) const {
        return o < *this;
    }
 
    inline bool operator>=(TfToken const& o) const {
        return !(*this < o);
    }
 
    inline bool operator<=(TfToken const& o) const {
        return !(*this > o);
    }
 
    operator std::string const& () const { return GetString(); }
    
    bool IsEmpty() const { return _rep.GetLiteral() == 0; }
 
    bool IsImmortal() const {
        if (!_rep.BitsAs<bool>()) {
            return true;
        }
        // There is no synchronization or ordering constraints between this read
        // and other reads/writes, so relaxed memory order suffices.
        bool immortal = !(_rep->_refCount.load(std::memory_order_relaxed) & 1);
        if (immortal) {
            // Our belief is wrong, update our cache of countedness.
            _rep.SetBits(false);
        }
        return immortal;
    }
 
    friend TF_API std::ostream &operator <<(std::ostream &stream, TfToken const&);
 
    template <class HashState>
    friend void
    TfHashAppend(HashState &h, TfToken const &token) {
        h.Append(token._rep.Get());
    }
 
private:
    // Add global swap overload.
    friend void swap(TfToken &lhs, TfToken &rhs) {
        lhs.Swap(rhs);
    }
 
    void _AddRef() const {
        if (!_rep.BitsAs<bool>()) {
            // Not counted, do nothing.
            return;
        }
        // We believe this rep is refCounted.
        if (!_rep->IncrementAndCheckCounted()) {
            // Our belief is wrong, update our cache of countedness.
            _rep.SetBits(false);
        }
    }
 
    void _RemoveRef() const {
        if (!_rep.BitsAs<bool>()) {
            // Not counted, do nothing.
            return;
        }
        // Decrement the refcount.
        _rep->Decrement();
    }
 
    struct _Rep {
        _Rep() = default;
 
        // A rep's identity in the token table is its NUL-terminated c-string
        // (see Tf_TokenRegistry::_Eq), so _str must hold exactly that.
        // Building it from the c-string trims any content past an embedded NUL,
        // which keeps _str.size() == strlen(_cstr) and makes a token's
        // observable content independent of whether a char * or std::string
        // happened to intern it.
        explicit _Rep(char const *str,
                      unsigned setNum,
                      uint64_t compareCode)
            : _refCount(0)
            , _setNum(setNum)
            , _compareCode(compareCode)
            , _str(str)
            , _cstr(_str.c_str()) {}
 
        explicit _Rep(std::string const &str,
                      unsigned setNum,
                      uint64_t compareCode)
            : _Rep(str.c_str(), setNum, compareCode) {}
 
        // Make sure we reacquire _cstr from _str on copy and assignment
        // to avoid holding on to a dangling pointer. However, if rhs'
        // _cstr member doesn't come from its _str, just copy it directly
        // over. This is to support lightweight _Rep objects used for 
        // internal lookups.
        _Rep(_Rep const &rhs)
            : _refCount(rhs._refCount.load(std::memory_order_relaxed))
            , _setNum(rhs._setNum)
            , _compareCode(rhs._compareCode)
            , _str(rhs._str)
            , _cstr(rhs._str.c_str() == rhs._cstr ? _str.c_str() : rhs._cstr) {}
 
        _Rep &operator=(_Rep const &rhs) {
            _refCount = rhs._refCount.load(std::memory_order_relaxed);
            _setNum = rhs._setNum;
            _compareCode = rhs._compareCode;
            _str = rhs._str;
            _cstr = (rhs._str.c_str() == rhs._cstr ? _str.c_str() : rhs._cstr);
            return *this;
        }
 
        inline bool IncrementAndCheckCounted() const {
            // Refcounts are manipulated by add/sub 2, since the lowest-order
            // bit indicates whether or not the rep is counted.
            return _refCount.fetch_add(2, std::memory_order_relaxed) & 1;
        }
 
        inline void Decrement() const {
            // Refcounts are manipulated by add/sub 2, since the lowest-order
            // bit indicates whether or not the rep is counted.
            _refCount.fetch_sub(2, std::memory_order_release);
        }
 
        mutable std::atomic_uint _refCount;
        unsigned _setNum;
        uint64_t _compareCode;
        std::string _str;
        char const *_cstr;
    };
 
    friend struct TfTokenFastArbitraryLessThan;
    friend struct Tf_TokenRegistry;
    
    TF_API static std::string const& _GetEmptyString();
 
    mutable TfPointerAndBits<const _Rep> _rep;
};
 
inline size_t
TfToken::Hash() const
{
    return TfHash()(*this);
}
 
struct TfTokenFastArbitraryLessThan {
    inline bool operator()(TfToken const &lhs, TfToken const &rhs) const {
        return lhs._rep.Get() < rhs._rep.Get();
    }
};
            
TF_API std::vector<TfToken>
TfToTokenVector(const std::vector<std::string> &sv);
 
TF_API std::vector<std::string>
TfToStringVector(const std::vector<TfToken> &tv);
 
inline size_t hash_value(const TfToken& x) { return x.Hash(); }
 
typedef std::vector<TfToken> TfTokenVector;
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_TF_TOKEN_H