nekohook/modules/source2013/sdk/public/tier1/utlbidirectionalset.h

//========= Copyright Valve Corporation, All rights reserved. ============//
//
// Purpose: Bi-directional set. A Bucket knows about the elements that lie
// in it, and the elements know about the buckets they lie in.
//
// $Revision: $
// $NoKeywords: $
//=============================================================================//

#ifndef UTLBIDIRECTIONALSET_H
#define UTLBIDIRECTIONALSET_H

#ifdef _WIN32
#pragma once
#endif

#include "tier0/dbg.h"
#include "utllinkedlist.h"

//-----------------------------------------------------------------------------
// Templatized helper class to deal with the kinds of things that spatial
// partition code always seems to have; buckets with lists of lots of elements
// and elements that live in lots of buckets. This makes it really quick to
// add and remove elements, and to iterate over all elements in a bucket.
//
// For this to work, you must initialize the set with two functions one that
// maps from bucket to the index of the first element in that bucket, and one
// that maps from element to the index of the first bucket that element lies in.
// The set will completely manage the index, it's just expected that those
// indices will be stored outside the set.
//
// S is the storage type of the index; it is the type that you may use to
// save indices into memory. I is the local iterator type, which you should
// use in any local scope (eg, inside a for() loop.) The reason for this is
// that you may wish to use unsigned shorts inside the structs you are
// saving with a CBidirectionalSet; but 16-bit arithmetic is catastrophically
// slow on a PowerPC -- during testing we saw CBidirectionalSet:: operations
// consume as much as 8% of the frame.
//
// For this reason, on the 360, the handles have been typedef'd to native
// register types (U32) which are accepted as parameters by the functions.
// The implicit assumption is that CBucketHandle and CElementHandle can
// be safely cast to ints! You can increase to U64 without performance
// penalty if necessary; the PowerPC is a 64-bit processor.
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I = S>
class CBidirectionalSet {
   public:
    // Install methods to get at the first bucket given a element
    // and vice versa...
    typedef S& (*FirstElementFunc_t)(CBucketHandle);
    typedef S& (*FirstBucketFunc_t)(CElementHandle);

#ifdef _X360
    typedef uint32 CBucketHandlePram;
    typedef uint32 CElementHandlePram;
#else
    typedef CBucketHandle CBucketHandlePram;
    typedef CElementHandle CElementHandlePram;
#endif

    // Constructor
    CBidirectionalSet();

    // Call this before using the set
    void Init(FirstElementFunc_t elemFunc, FirstBucketFunc_t bucketFunc);

    // Add an element to a particular bucket
    void AddElementToBucket(CBucketHandlePram bucket,
                            CElementHandlePram element);

    // Prevalidate an add to a particular bucket
    // NOTE: EXPENSIVE!!!
    void ValidateAddElementToBucket(CBucketHandlePram bucket,
                                    CElementHandlePram element);

    // Test if an element is in a particular bucket.
    // NOTE: EXPENSIVE!!!
    bool IsElementInBucket(CBucketHandlePram bucket,
                           CElementHandlePram element);

    // Remove an element from a particular bucket
    void RemoveElementFromBucket(CBucketHandlePram bucket,
                                 CElementHandlePram element);

    // Remove an element from all buckets
    void RemoveElement(CElementHandlePram element);
    void RemoveBucket(CBucketHandlePram element);

    // Used to iterate elements in a bucket; I is the iterator
    I FirstElement(CBucketHandlePram bucket) const;
    I NextElement(I idx) const;
    CElementHandle Element(I idx) const;

    // Used to iterate buckets associated with an element; I is the iterator
    I FirstBucket(CElementHandlePram bucket) const;
    I NextBucket(I idx) const;
    CBucketHandle Bucket(I idx) const;

    static S InvalidIndex();

    // Ensure capacity
    void EnsureCapacity(int count);

    // Deallocate....
    void Purge();

    int NumAllocated(void) const;

   private:
    struct BucketListInfo_t {
        CElementHandle m_Element;
        S m_BucketListIndex;  // what's the m_BucketsUsedByElement index of the
                              // entry?
    };

    struct ElementListInfo_t {
        CBucketHandle m_Bucket;
        S m_ElementListIndex;  // what's the m_ElementsInBucket index of the
                               // entry?
    };

    // Maintains a list of all elements in a particular bucket
    CUtlLinkedList<BucketListInfo_t, S, true, I> m_ElementsInBucket;

    // Maintains a list of all buckets a particular element lives in
    CUtlLinkedList<ElementListInfo_t, S, true, I> m_BucketsUsedByElement;

    FirstBucketFunc_t m_FirstBucket;
    FirstElementFunc_t m_FirstElement;
};

//-----------------------------------------------------------------------------
// Constructor
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::CBidirectionalSet() {
    m_FirstBucket = NULL;
    m_FirstElement = NULL;
}

//-----------------------------------------------------------------------------
// Call this before using the set
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::Init(
    FirstElementFunc_t elemFunc, FirstBucketFunc_t bucketFunc) {
    m_FirstBucket = bucketFunc;
    m_FirstElement = elemFunc;
}

//-----------------------------------------------------------------------------
// Adds an element to the bucket
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S,
                       I>::ValidateAddElementToBucket(CBucketHandlePram bucket,
                                                      CElementHandlePram
                                                          element) {
#ifdef _DEBUG
    // Make sure that this element doesn't already exist in the list of elements
    // in the bucket
    I elementInBucket = m_FirstElement(bucket);
    while (elementInBucket != m_ElementsInBucket.InvalidIndex()) {
        // If you hit an Assert here, fix the calling code.  It's too expensive
        // to ensure that each item only shows up once here.  Hopefully you can
        // do something better outside of here.
        Assert(m_ElementsInBucket[elementInBucket].m_Element != element);
        elementInBucket = m_ElementsInBucket.Next(elementInBucket);
    }
    // Make sure that this bucket doesn't already exist in the element's list of
    // buckets.
    I bucketInElement = m_FirstBucket(element);
    while (bucketInElement != m_BucketsUsedByElement.InvalidIndex()) {
        // If you hit an Assert here, fix the calling code.  It's too expensive
        // to ensure that each item only shows up once here.  Hopefully you can
        // do something better outside of here.
        Assert(m_BucketsUsedByElement[bucketInElement].m_Bucket != bucket);
        bucketInElement = m_BucketsUsedByElement.Next(bucketInElement);
    }
#endif
}

//-----------------------------------------------------------------------------
// Adds an element to the bucket
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::AddElementToBucket(
    CBucketHandlePram bucket, CElementHandlePram element) {
    Assert(m_FirstBucket && m_FirstElement);

    // Allocate new element + bucket entries
    I idx = m_ElementsInBucket.Alloc(true);
    I list = m_BucketsUsedByElement.Alloc(true);

    // Store off the element data
    m_ElementsInBucket[idx].m_Element = element;
    m_ElementsInBucket[idx].m_BucketListIndex = list;

    // Here's the bucket data
    m_BucketsUsedByElement[list].m_Bucket = bucket;
    m_BucketsUsedByElement[list].m_ElementListIndex = idx;

    // Insert the element into the list of elements in the bucket
    S& firstElementInBucket = m_FirstElement(bucket);
    if (firstElementInBucket != m_ElementsInBucket.InvalidIndex())
        m_ElementsInBucket.LinkBefore(firstElementInBucket, idx);
    firstElementInBucket = idx;

    // Insert the bucket into the element's list of buckets
    S& firstBucketInElement = m_FirstBucket(element);
    if (firstBucketInElement != m_BucketsUsedByElement.InvalidIndex())
        m_BucketsUsedByElement.LinkBefore(firstBucketInElement, list);
    firstBucketInElement = list;
}

//-----------------------------------------------------------------------------
// Test if an element is in a particular bucket.
// NOTE: EXPENSIVE!!!
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
bool CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::IsElementInBucket(
    CBucketHandlePram bucket, CElementHandlePram element) {
    // Search through all elements in this bucket to see if element is in there.
    I elementInBucket = m_FirstElement(bucket);
    while (elementInBucket != m_ElementsInBucket.InvalidIndex()) {
        if (m_ElementsInBucket[elementInBucket].m_Element == element) {
            return true;
        }
        elementInBucket = m_ElementsInBucket.Next(elementInBucket);
    }
    return false;
}

//-----------------------------------------------------------------------------
// Remove an element from a particular bucket
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S,
                       I>::RemoveElementFromBucket(CBucketHandlePram bucket,
                                                   CElementHandlePram element) {
    // FIXME: Implement me!
    Assert(0);
}

//-----------------------------------------------------------------------------
// Removes an element from all buckets
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::RemoveElement(
    CElementHandlePram element) {
    Assert(m_FirstBucket && m_FirstElement);

    // Iterate over the list of all buckets the element is in
    I i = m_FirstBucket(element);
    while (i != m_BucketsUsedByElement.InvalidIndex()) {
        CBucketHandlePram bucket = m_BucketsUsedByElement[i].m_Bucket;
        I elementListIndex = m_BucketsUsedByElement[i].m_ElementListIndex;

        // Unhook the element from the bucket's list of elements
        if (elementListIndex == m_FirstElement(bucket))
            m_FirstElement(bucket) = m_ElementsInBucket.Next(elementListIndex);
        m_ElementsInBucket.Free(elementListIndex);

        I prevNode = i;
        i = m_BucketsUsedByElement.Next(i);
        m_BucketsUsedByElement.Free(prevNode);
    }

    // Mark the list as empty
    m_FirstBucket(element) = m_BucketsUsedByElement.InvalidIndex();
}

//-----------------------------------------------------------------------------
// Removes a bucket from all elements
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::RemoveBucket(
    CBucketHandlePram bucket) {
    // Iterate over the list of all elements in the bucket
    I i = m_FirstElement(bucket);
    while (i != m_ElementsInBucket.InvalidIndex()) {
        CElementHandlePram element = m_ElementsInBucket[i].m_Element;
        I bucketListIndex = m_ElementsInBucket[i].m_BucketListIndex;

        // Unhook the bucket from the element's list of buckets
        if (bucketListIndex == m_FirstBucket(element))
            m_FirstBucket(element) =
                m_BucketsUsedByElement.Next(bucketListIndex);
        m_BucketsUsedByElement.Free(bucketListIndex);

        // Remove the list element
        I prevNode = i;
        i = m_ElementsInBucket.Next(i);
        m_ElementsInBucket.Free(prevNode);
    }

    // Mark the bucket list as empty
    m_FirstElement(bucket) = m_ElementsInBucket.InvalidIndex();
}

//-----------------------------------------------------------------------------
// Ensure capacity
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::EnsureCapacity(
    int count) {
    m_ElementsInBucket.EnsureCapacity(count);
    m_BucketsUsedByElement.EnsureCapacity(count);
}

//-----------------------------------------------------------------------------
// Deallocate....
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
void CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::Purge() {
    m_ElementsInBucket.Purge();
    m_BucketsUsedByElement.Purge();
}

//-----------------------------------------------------------------------------
// Number of elements allocated in each linked list (should be the same)
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
int CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::NumAllocated(
    void) const {
    Assert(m_ElementsInBucket.NumAllocated() ==
           m_BucketsUsedByElement.NumAllocated());
    return m_ElementsInBucket.NumAllocated();
}

//-----------------------------------------------------------------------------
// Invalid index for iteration..
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
inline S
CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::InvalidIndex() {
    return CUtlLinkedList<CElementHandle, I>::InvalidIndex();
}

//-----------------------------------------------------------------------------
// Used to iterate elements in a bucket; I is the iterator
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
inline I CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::FirstElement(
    CBucketHandlePram bucket) const {
    Assert(m_FirstElement);
    return m_FirstElement(bucket);
}

template <class CBucketHandle, class CElementHandle, class S, class I>
inline I CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::NextElement(
    I idx) const {
    return m_ElementsInBucket.Next(idx);
}

template <class CBucketHandle, class CElementHandle, class S, class I>
inline CElementHandle
CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::Element(I idx) const {
    return m_ElementsInBucket[idx].m_Element;
}

//-----------------------------------------------------------------------------
// Used to iterate buckets an element lies in; I is the iterator
//-----------------------------------------------------------------------------
template <class CBucketHandle, class CElementHandle, class S, class I>
inline I CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::FirstBucket(
    CElementHandlePram element) const {
    Assert(m_FirstBucket);
    return m_FirstBucket(element);
}

template <class CBucketHandle, class CElementHandle, class S, class I>
inline I CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::NextBucket(
    I idx) const {
    return m_BucketsUsedByElement.Next(idx);
}

template <class CBucketHandle, class CElementHandle, class S, class I>
inline CBucketHandle
CBidirectionalSet<CBucketHandle, CElementHandle, S, I>::Bucket(I idx) const {
    return m_BucketsUsedByElement[idx].m_Bucket;
}

#endif  // UTLBIDIRECTIONALSET_H