PDGE_PropagateGroup.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * COMMENTS:
 */

#ifndef __PDGE_PROPAGATE_GROUP_H__
#define __PDGE_PROPAGATE_GROUP_H__

#include "PDGE_API.h"

#include "PDGE_Dependency.h"
#include "PDGE_DependencyOwner.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayMap.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_TBBSpinLock.h>

/*
 * Provides a mechanism for a dependency owner to wait for all descendants
 * from a given upstream dependency, without knowing what they are ahead of
 * time. For example, this is used for targeted partitioning features and
 * feedback loops in $PDG.
 */
class PDGE_API PDGE_PropagateGroup : UT_NonCopyable
{
public:
    /// Constructs a new propagate group with the specified owner. The owner
    /// is used to when connecting this group to input groups and adding
    /// entries that should only propagate to a certain depth or target node.
                                PDGE_PropagateGroup(PDGE_DependencyOwner* owner);
    virtual                     ~PDGE_PropagateGroup();

    /// Returns the total memory usage of this propagate groiup
    int64                       getMemoryUsage(bool inclusive) const;

    /// Adds a target owner to the set of targets associated with this group.
    /// These are the owners that the group may target, and the group will not
    /// recurse beyond them when adding dependencies.
    inline void                 addTarget(PDGE_DependencyOwner* target)
                                    { myTargetOwners.insert(target); }

    /// Adds an input group to this propagate group. Dependencies are added
    /// on input group entries, and propagate back down to this group during
    /// evaluation.
    inline void                 addInputGroup(PDGE_PropagateGroup* input_group)
                                    { myInputGroups.append(input_group); }

    /// Resets the propagate group. This will free all owned dependencies and
    /// clear all structures including input groups and targets.
    void                        reset(PDGE_Dependency* extra_dependency);

    /// Adds an propagation entry to this group. The entry must have a target
    /// owner and a root dependency. Optionally, an additional dependent can
    /// be passed that will automatically be made to depend on the new entry.
    ///
    /// The root is the source dependency for which the entry is associated
    /// with. The entry will wait for the root and all of its descendants
    /// between the target owner and this group.
    void                        addEntry(
                                    PDGE_DependencyOwner* target,
                                    PDGE_Dependency* root,
                                    PDGE_Dependency* dependent);
    
    /// Copies relevant propagate depenencies from source onto the specified
    /// downstream dependent, based on what propagate entries exist in this map.
    void                        propagateDependencies(
                                    PDGE_Dependency* source,
                                    PDGE_Dependency* destination);

    /// Returns the list of dependency owners for a propagate dependency owned
    /// by this group.
    void                        upstreamOwners(
                                    PDGE_DependencyOwner::Array& owners,
                                    PDGE_Dependency* dependency) const;

    /// Returns the root owner for a propagate dependency owned by this group
    PDGE_DependencyOwner*       rootOwner(PDGE_Dependency* dependent) const;

private:
    using Array = UT_Array<PDGE_PropagateGroup*>;
    using Map   = UT_ArrayMap<PDGE_Dependency*, PDGE_Dependency*>;

    void                        propagateInternal(PDGE_Dependency* source,
                                                  PDGE_Dependency* destination);
    PDGE_Dependency*            addEntryInternal(
                                    PDGE_DependencyOwner* target,
                                    const PDGE_DependencyOwner::Set& targets,
                                    PDGE_Dependency* root,
                                    PDGE_Dependency* dependent);
    PDGE_Dependency*            addEntryInternal(
                                    PDGE_Dependency* root);
private:
    Array                       myInputGroups;
    Map                         myPropagateDependencies;
    Map                         myDependents;
    PDGE_DependencyOwner::Set   myTargetOwners;
    PDGE_DependencyOwner*       myOwner;
    PDGE_Dependency*            myExtraDependency;
    mutable UT_TBBSpinLock      myLock;
};

#endif