GA_PageIterator.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.
 *
 * NAME:        GA_PageIterator.h ( GA Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GA_PageIterator__
#define __GA_PageIterator__

#include "GA_API.h"
#include "GA_Iterator.h"
#include "GA_Range.h"
#include "GA_SplittableRange.h"
#include "GA_Types.h"

#include <UT/UT_ThreadedAlgorithm.h>

#include <stddef.h>


class GA_API GA_PageIterator
{
public:
    GA_PageIterator(const GA_SplittableRange &range,
                const UT_JobInfo *jobinfo=NULL)
        : myRange(range)
        , myJobInfo(jobinfo)
        , myCurr(0)
        , myPageCount(range.getPageCount())
    {
        if (myJobInfo)
            myCurr = myJobInfo->nextTask();
    }
    GA_PageIterator(const GA_PageIterator &pit)
        : myRange(pit.myRange)
        , myJobInfo(pit.myJobInfo)
        , myCurr(pit.myCurr)
        , myPageCount(pit.myPageCount)
    {
    }
    ~GA_PageIterator() {}

    /// Assignment operator
    GA_PageIterator     &operator=(const GA_PageIterator &src)
                        {
                            myRange = src.myRange;
                            myJobInfo = src.myJobInfo;
                            myCurr = src.myCurr;
                            myPageCount = src.myPageCount;
                            return *this;
                        }
    /// Equality operator
    bool                operator==(const GA_PageIterator &src) const
                        {
                            return myRange == src.myRange &&
                                myJobInfo == src.myJobInfo &&
                                myCurr == src.myCurr &&
                                myPageCount == src.myPageCount;
                        }
    bool                operator!=(const GA_PageIterator &src) const
                            { return !(*this == src); }

    /// @{
    /// Return the offset for the beginning of the current page
    GA_Offset   getFirstOffsetInPage() const
                {
                    return myRange.getFirstOffsetInPage(myCurr);
                }
    GA_Offset   operator*() const       { return getFirstOffsetInPage(); }
    /// @}

    /// @{
    /// Iterator interface
    /// @warning The post-increment operator has a side-effect since the value
    /// returned is the iterator @b after the increment (not before)
    void        rewind()        { myCurr = 0; }
    bool        atEnd() const   { return myCurr >= myPageCount; }
    void        advance()
                {
                    if (myJobInfo)
                        myCurr = myJobInfo->nextTask();
                    else
                        myCurr++;
                }
    GA_PageIterator     &operator++()           { advance(); return *this; }
    // No post inc as it is harmful.
    /// @}

    /// @{
    /// Begin iterating over the offsets in a page
    auto begin() const  { return GA_Iterator(
                                        myRange.getPageElementRange(myCurr)); }
    auto end() const    { return myRange.end(); }
    /// @}

private:
    GA_SplittableRange   myRange;
    const UT_JobInfo    *myJobInfo;
    GA_Size              myCurr, myPageCount;
};

/// Invokes a body across each block within a page iterator, avoiding
/// the double loop you normally needed.  
/// Usage:
/// GA_PageIterator pit(...);
/// GAforEachPageBlock(pit, [&](GA_Offset start, GA_Offset end)
/// {
///     for (GA_Offset off = start; off < end; off++)
///     { /* work with off */ }
/// });
template <typename Body>
void
GAforEachPageBlock(GA_PageIterator &page_iterator,
                   const Body &body)
{
    GA_Offset           start, end;

    for ( ; !page_iterator.atEnd(); ++page_iterator)
    {
        for (GA_Iterator it(page_iterator.begin());
             it.blockAdvance(start, end); )
        {
            body(start, end);
        }
    }
}

/// Invokes the body approximately once per worker thread with
/// a shared atomic int to provide load-balanced iteration over the
/// pages in the range.
/// shouldthread allows you to easily disable threading, for example if
/// you know some cases are not threadsafe or you have a larger grain
/// size.
/// Body Signature: void body(GA_PageIterator page_iterator)
/// Usage:
/// GAparallelForEachPage(range, shouldthread, [&](GA_PageIterator pit)
/// {
///     /* Thread local data structures / scratchpads */
///     UT_IntArray scratchpad;
///     GA_ROPageHandleF pagehandle;  /* page handles must be per thread */
///     GAforEachPageBlock(pit, [&](GA_Offset start, GA_Offset end)
///     {
///         pagehandle.setPage(start);
///         for (GA_Offset off = start; off < end; off++)
///         { /* Process off, using scratchpad */ }
///     });
/// });
///
/// NOTE: Using [&] capture on GAparallelForEachPage will share the outer
/// scope's stack variables between threads - you must treat them as const
/// (and in particular, re-build pagehandles inside this loop.  For non
/// trivial loops explicit binding may be safer.
template <typename Body>
void
GAparallelForEachPage(const GA_Range &range, bool shouldthread, 
                        const Body &body)
{
    GA_SplittableRange srange(range);

    int npages = srange.getPageCount();
    if (npages == 0)
        return;

    int nworkers(UT_Thread::getNumProcessors());
    UT_ASSERT(nworkers >= 1);

    nworkers = SYSmin(nworkers, npages);
    if (!shouldthread || nworkers == 1)
    {
        // Serial case
        body(GA_PageIterator(srange));
        return;
    }

    // Split across number of workers, with each thread using the atomic int
    // to query the next page to be run (similar to UT_ThreadedAlgorithm)
    SYS_AtomicInt<int>  nextpage(0);

    UTparallelFor(UT_BlockedRange<int>(0, nworkers),
            [&](const UT_BlockedRange<int> &range) 
    {
        // There should be only one job id in the range, but we
        // use this construction anyways... (If there were more,
        // the later ones would all trivially fail when they start
        // up and nextTask...)
        for (int jobid : range.items())
        {
            UT_JobInfo  info(jobid, nworkers, nullptr, &nextpage);

            body(GA_PageIterator(srange, &info));
        }
    });
}

/// Define macros roughly equivalent to FOR_INFOTASKS (in
/// UT_ThreadedAlgorithm).  This will break up the full range into a load
/// balanced iteration over pages.  For example:
/// GA_FOR_INFOTASKS(info, gdp->getPointRange(), it) 
/// {
///      doSomething(it.getOrder());            // Use point number
///      doSomething(it.getOffset());   // Use point offset
/// }
#define GA_FOR_INFORANGE(info, full_range, IT_NAME)     \
    GA_SplittableRange  lcl_prange(full_range); \
    for (GA_PageIterator pit=lcl_prange.beginPages(info); \
            !pit.atEnd(); ++pit) \
        for (GA_Iterator IT_NAME = pit.begin(); !IT_NAME.atEnd(); ++IT_NAME)

/// Like FOR_INFOTASKS_BOSS, iterate with an optional opInterrupt for every
/// block completed.
#define GA_FOR_INFORANGE_BOSS(info, full_range, IT_NAME, boss)  \
    GA_SplittableRange  lcl_prange(full_range); \
    for (GA_PageIterator pit=lcl_prange.beginPages(info); \
            !pit.atEnd() && !boss->opInterrupt(); ++pit) \
        for (GA_Iterator IT_NAME = pit.begin(); !IT_NAME.atEnd(); ++IT_NAME)

/// Iterate over all points for the given info
#define GA_FOR_INFO_ALLPOINTS(gdp, info, IT_NAME) \
    GA_SplittableRange  lcl_prange(gdp->getPointRange()); \
    for (GA_PageIterator pit=lcl_prange.beginPages(info); \
            !pit.atEnd(); ++pit) \
        for (GA_Iterator IT_NAME = pit.begin(); !IT_NAME.atEnd(); ++IT_NAME)

/// Iterate over all points for the given info with a UT_Interrupt
#define GA_FOR_INFO_ALLPOINTS_BOSS(gdp, info, IT_NAME, boss) \
    GA_SplittableRange  lcl_prange(gdp->getPointRange()); \
    for (GA_PageIterator pit=lcl_prange.beginPages(info); \
            !pit.atEnd() && !boss->opInterrupt(); ++pit) \
        for (GA_Iterator IT_NAME = pit.begin(); !IT_NAME.atEnd(); ++IT_NAME)


/// Iterate over all points for the given info with a UT_Interrupt
#define GA_FOR_INFO_GROUP_POINTS_BOSS(gdp, pointgrp, info, IT_NAME, boss) \
    GA_SplittableRange  lcl_prange(gdp->getPointRange(pointgrp)); \
    for (GA_PageIterator pit=lcl_prange.beginPages(info); \
            !pit.atEnd() && !boss->opInterrupt(); ++pit) \
        for (GA_Iterator IT_NAME = pit.begin(); !IT_NAME.atEnd(); ++IT_NAME)


#endif