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

#ifndef __UT_TASKGROUP_H_INCLUDED__
#define __UT_TASKGROUP_H_INCLUDED__

#ifndef __TBB_show_deprecation_message_task_H
    #define __TBB_show_deprecation_message_task_H
    #define UT_TASKGROUP_RESTORE_DEPRECATION_MESSAGE
#endif

#include "UT_API.h"
#include "UT_Thread.h"
#include <tbb/parallel_for.h>
#include <tbb/task.h>
#include <tbb/task_group.h>
#include <utility>

class UT_API UT_TaskGroupContext : private tbb::task_group_context
{
    typedef tbb::task_group_context me;

public:

    enum KindType
    {
        ISOLATED = me::isolated,
        BOUND = me::bound
    };

    /// Constructs an empty task_group_context.
    ///
    /// If relation_to_parent is bound, the task_group_context will become a
    /// child of the innermost running task's group when it is first spawned.
    /// If this call is made directly from the user thread, the effect will be
    /// as if relation_to_parent were isolated. If relation_to_parent is
    /// isolated, it has no parent task_group_context.
                UT_TaskGroupContext(KindType relation_to_parent = BOUND)
                    : task_group_context((kind_type)relation_to_parent)
                {
                }

    /// Destroys an empty task_group_context. The behavior is undefined if
    /// there are still extant tasks associated with this task_group_context.
                ~UT_TaskGroupContext() = default;

    /// Reinitializes this to uncancelled state.
    ///
    /// @warn This method is only safe to call once all tasks associated with
    /// the group's subordinate groups have completed. This method must not be
    /// invoked concurrently by multiple threads.
    void        reset()
                {
                    me::reset();
                }

    /// Requests that tasks in group be cancelled.
    ///
    /// @return False if group is already cancelled; true otherwise. If
    ///         concurrently called by multiple threads, exactly one call
    ///         returns true and the rest return false.
    bool        cancelGroupExecution()
                {
                    return me::cancel_group_execution();
                }

    /// @return True if group has received cancellation.
    bool        isGroupExecutionCancelled() const
                {
                    return me::is_group_execution_cancelled();
                }

    /// Cancel the entire current task group context when run within a task
    static void cancelCurrentGroupExecution()
                {
                    // TODO: In oneTBB, this becomes,
                    //          current_context()->cancel_group_execution()
                    tbb::task::self().cancel_group_execution();
                }
};

class UT_API UT_TaskGroup : private tbb::task_group
{
    typedef tbb::task_group     me;

public:
    UT_TaskGroup()
        : tbb::task_group()
    {
    }
    ~UT_TaskGroup()
    {
    }

    template <typename F>
    void        run(F &&f)
                {
                    me::run(std::forward<F>(f));
                }

    template <typename F>
    void        run(tbb::task_handle<F> &f)
                {
                    me::run(f);
                }

    template <typename F>
    void        runAndWait(const F &f)
                {
                    me::run_and_wait(f);
                }

    template <typename F>
    void        runAndWait(tbb::task_handle<F> &f)
                {
                    me::run_and_wait(f);
                }

    // American English
    bool        isCanceling()   { return me::is_canceling(); }
    // British English
    bool        isCancelling()  { return me::is_canceling(); }

    tbb::task_group_status      wait()          { return me::wait(); }
    void                        cancel()        { me::cancel(); }
};

/// Spawn a UTparallelFor() task to a UT_TaskGroup
/// @see UTparallelFor(), UT_TaskGroup
template <typename RANGE, typename BODY>
void
UTparallelForRunInTaskGroup(
        UT_TaskGroup &task_group,
        RANGE &&range,
        BODY &&body)
{
    // We forward range and body into the lambda so that if they were movable
    // temporaries, this can avoid an extra copy.
    task_group.run(
        [range = std::forward<RANGE>(range), body = std::forward<BODY>(body)]()
        {
            UT_ASSERT(UT_Thread::isThreadingEnabled());
            tbb::parallel_for(range, body, tbb::simple_partitioner());
        });
}

#ifdef UT_TASKGROUP_RESTORE_DEPRECATION_MESSAGE
    #undef __TBB_show_deprecation_message_task_H
    #undef UT_TASKGROUP_RESTORE_DEPRECATION_MESSAGE
#endif

#endif // __UT_TASKGROUP_H_INCLUDED__