UT_TaskArena.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_TaskArena.h (UT Library, C++)
 *
 * COMMENTS:    Wrapper for tbb::task_arena
 */

#pragma once

#ifndef __UT_TASKARENA_H_INCLUDED__
#define __UT_TASKARENA_H_INCLUDED__

#include "UT_API.h"
#include "UT_NonCopyable.h"
#include <SYS/SYS_AtomicInt.h>
#include <SYS/SYS_Types.h>

#include <tbb/task_arena.h>

#include <utility>

#include <stddef.h>


/// @file
/// @class UT_TaskArena
///
/// Simple wrapper for running code within a tbb::task_arena. For most usages,
/// you want to do this if you're going to spawn tasks with a lock held.
class UT_API UT_TaskArena
{
public:
    static const int automatic = -1;

    /// Creates task_arena with certain concurrency limits
    ///
    /// Sets up settings only, real construction is deferred till the first
    /// method invocation.
    /// @arg max_concurrency specifies total number of slots in arena where
    ///      threads work
    /// @arg reserved_for_masters specifies number of slots to be used by
    ///      master threads only.
    ///      Value of 1 is default and reflects behavior of implicit arenas.
    UT_TaskArena(int max_concurrency = automatic,
                 unsigned reserved_for_masters = 1);
    ~UT_TaskArena();

    UT_NON_COPYABLE(UT_TaskArena)

    /// Joins the arena and executes a functor, then returns
    ///
    /// If not possible to join, wraps the functor into a task, enqueues it and
    /// waits for task completion. Can decrement the arena demand for workers,
    /// causing a worker to leave and free a slot to the calling thread.
    /// @{
    template <typename F>
    void execute(F &functor)
    {
        internalExecute(&UT_TaskArena::callback<F>, &functor);
    }

    template <typename F>
    void execute(const F &functor)
    {
        internalExecute(&UT_TaskArena::callbackConst<F>, &functor);
    }
    /// @}

    /// Executes functor and by locking the given mutex and running it in a
    /// task_arena for exclusive work isolation.
    /// @{
    template <typename M, typename F>
    static void
    lockedExecute(M &mutex, F &functor)
    {
        typename M::Scope scope(mutex);
        UT_TaskArena arena;
        arena.execute(functor);
    }

    template <typename M, typename F>
    static void
    lockedExecute(M &mutex, const F &functor)
    {
        typename M::Scope scope(mutex);
        UT_TaskArena arena;
        arena.execute(functor);
    }
    /// @}

    /// Enqueues a task into the arena to process a functor, and immediately
    /// returns.  Does not require the calling thread to join the arena.
    template<typename F>
    static void
    enqueue(F&& f)
    {
        tbb::task_arena arena(tbb::task_arena::attach{});
        arena.enqueue(std::forward<F>(f));
    }

    /// Call this before using the arena if execute may be called from multiple
    /// threads.
    void initialize();

    int maxConcurrency() const;

    // Debug counter. Only modified on debug builds
    static SYS_AtomicInt32 theArenaCount;

private:

    template <typename F>
    static void callback(void *data)
    {
        (*reinterpret_cast<F *>(data))();
    }
    template <typename F>
    static void callbackConst(const void *data)
    {
        (*reinterpret_cast<const F *>(data))();
    }

    void    internalExecute(void (*callback)(void *), void *data);
    void    internalExecute(void (*callback)(const void *), const void *data);

private:
    static const size_t SIZEOF_ARENA = 48;
    alignas(tbb::task_arena) uint8 myArena[SIZEOF_ARENA];
};

#endif // __UT_TASKARENA_H_INCLUDED__