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

#pragma once

#ifndef __UT_TaskExclusive__
#define __UT_TaskExclusive__

#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_AtomicInt.h>

#include <oneapi/tbb/collaborative_call_once.h>

#include <utility>

/// This is a lock-free implementation for exclusive task execution.  That is,
/// a task which needs to be performed once (i.e. std::once).  However, this
/// construct will allow TBB to recycle blocked tasks so they can be used for
/// other processing.
///
/// This can be used as an alternate to a lock.  If code underneath a lock
/// calls into TBB, this can lead to a deadlock since TBB can steal a child
/// task to complete a parent task outside the lock.  This typically requires a
/// separate task arena.  A lock will also block a thread, preventing it from
/// participating in other tasks.
///
/// UT_TaskExclusive provides a good alternative, ensuring that only one thread
/// will execute the functor, and all other threads which wait for the functor
/// to finish will be allowed to participate in other computation (even to help
/// computing parallel tasks in the functor).
///
/// The class is templated on a functor which is used to actually perform the
/// execution.  The template functor needs to have a operator()() method.
///
/// For example, given a single Object which has a deferredInitialize() method
/// that may get called from multiple threads: @code
///    class Object
///    {
///        UT_TaskExclusive<Object> myExclusive;
///
///    public:
///        // Users call deferredInitialize when they want the object to be
///        // initialized.  However, it's possible the object may need to be
///        // initialized by multiple threads.  The object uses UT_TaskExclusive
///        // to ensure doInitialization() is only executed one time.
///        void deferredInitialize()
///        {
///            myExclusive.execute(*this);
///        }
///        void operator()()
///        {
///            // This method will only be called once, even if
///            // multiple threads invoke the deferredInitialize() method
///            // simultaneously.
///            doInitialization();
///        }
///    }
/// @endcode
/// If you have multiple methods that should only be called one time, you can
/// always create a nested object functor.
template <class T>
class UT_TaskExclusive
{
public:
    UT_TaskExclusive()
    {
        reset();
    }

    /// Execute the function.  This will guarantee the function has been
    /// run before the execute() function returns.  However, no locking will be
    /// done.
    ///
    /// If multiple threads try to call the function simultaneously, only one
    /// function will run, while the other will yield its cycles to other
    /// parallel tasks.  When the first task completes, both threads will
    /// return.
    void execute(T &func)
    {
        oneapi::tbb::collaborative_call_once(
            *myCollaborativeFlag, 
            [&] 
            {
                func();
                myIsDone.store(true);
            }
        );
    }

    /// Executes the function in this thread without any locking
    /// or protection.  Useful if the caller has already setup the
    /// appropriate lock.
    void executeNoThread(T &func)
    {
        if (!myIsDone.load())
        {
            func();
            myIsDone.store(true);
        }
    }

    /// Resetting the exclusive task should only be done when there's no
    /// possibility that any threads are trying to execute or relying on the
    /// results of the computation.
    void reset() 
    { 
        myCollaborativeFlag = 
            UTmakeUnique<oneapi::tbb::collaborative_once_flag>();
        myIsDone.store(false);
    }

    /// Test whether the function has been executed.  This is thread-safe, but
    /// doesn't count on other threads which may be in the process of running
    /// it.
    bool hasRun() const 
    { 
        return myIsDone.load();
    }

private:
    UT_UniquePtr<oneapi::tbb::collaborative_once_flag> myCollaborativeFlag;
    SYS_AtomicInt<bool> myIsDone;

};
#endif