ThreadPool.h

Go to the documentation of this file.

// Copyright Onix Solutions Limited [OnixS]. All rights reserved.
//
// This software owned by Onix Solutions Limited [OnixS] and is 
// protected by copyright law and international copyright treaties.
//
// Access to and use of the software is governed by the terms of the applicable 
// OnixS Software Services Agreement (the Agreement) and Customer end user license 
// agreements granting a non-assignable, non-transferable and non-exclusive license 
// to use the software for it's own data processing purposes under the terms defined 
// in the Agreement.
//
// Except as otherwise granted within the terms of the Agreement, copying or 
// reproduction of any part of this source code or associated reference material 
// to any other location for further reproduction or redistribution, and any 
// amendments to this copyright notice, are expressly prohibited.
//
// Any reproduction or redistribution for sale or hiring of the Software not in 
// accordance with the terms of the Agreement is a violation of copyright law.
//

#pragma once

#include <vector>

#include <OnixS/CME/ConflatedUDP/String.h>
#include <OnixS/CME/ConflatedUDP/Integral.h>
#include <OnixS/CME/ConflatedUDP/TinySet.h>

ONIXS_CONFLATEDUDP_NAMESPACE_BEGIN

/// Defines an abstraction for a task.
ONIXS_CONFLATEDUDP_EXPORTED_STRUCT Task
{
    /// Executes the given task. 
    virtual void run() = 0;
};

/// Zero-based index of CPU.
typedef Int32 CpuIndex;

/// Alias for collection of CPU indices.
typedef 
TinySet<CpuIndex> 
CpuIndices;

/// Represents a set of CPU indices.
ONIXS_CONFLATEDUDP_LTWT_CLASS ThreadAffinity
{
    CpuIndices indices_;

public:
    /// Initializes the empty set.
    ThreadAffinity()
    {
    }

    /// Initializes as a copy of the other set.
    ThreadAffinity(
        const ThreadAffinity& other)
        : indices_(other.indices_)
    {
    }

    /// Utilizes internal resources.
    ~ThreadAffinity()
    {
    }

    /// Indicates whether affinity is defined.
    operator bool() const
    {
        return indices_.empty();
    }

    /// Read-only access to the indices.
    const CpuIndices& cpus() const
    {
        return indices_;
    }

    /// Collection of the CPU indices.
    CpuIndices& cpus()
    {
        return indices_;
    }
};

/// Serializes thread affinity into a string. 
ONIXS_CONFLATEDUDP_EXPORTED 
void 
toStr(
    std::string&, 
    const ThreadAffinity&);

/// Serializes thread affinity into a string. 
inline 
std::string 
toStr(
    const ThreadAffinity& affinity)
{
    std::string str;

    toStr(str, affinity);

    return str;
}

//

ONIXS_CONFLATEDUDP_INTERNAL_CLASS_DECL
(
    TaskRunner
);

/// Manages group of threads executing user-defined tasks. 
ONIXS_CONFLATEDUDP_LTWT_CLASS ThreadPool
{
    typedef 
    std::vector<TaskRunner*> 
    Tasks;

    Tasks tasks_;

    const size_t capacity_;

    ThreadPool(
        const ThreadPool&);

    ThreadPool& 
    operator =(
        const ThreadPool&);

public:
    /// Initializes the pool of the requested capacity. 
    explicit 
    ThreadPool(
        size_t capacity)
        : capacity_(capacity)
    {
        tasks_.reserve(capacity);
    }

    /// Finalizes the instance. 
    ///
    /// Waits until all threads accomplish their tasks. 
    ~ThreadPool()
    {
        joinAll();
    }

    /// Number of active threads currently 
    /// busy executing user-defined tasks. 
    size_t size() const
    {
        return tasks_.size();
    }

    /// Maximal number of threads maintained by the given pool. 
    size_t capacity() const
    {
        return capacity_;
    }

    /// Spawns the new thread executing the given task. 
    /// 
    /// Raises exception if the number of active threads
    /// exceeds the predefined capacity of the pool. 
    void
    start(
        Task& task)
    {
        start(
            task, 
            ThreadAffinity());
    }

    /// Spawns the new thread executing the given task. 
    /// Binds the spawned thread to the defined set of 
    /// cores/processors.
    /// 
    /// Raises exception if the number of active threads
    /// exceeds the predefined capacity of the pool. 
    ONIXS_CONFLATEDUDP_LTWT_EXPORTED
    void 
    start(
        Task&, 
        const ThreadAffinity&);

    /// Blocks until all threads accomplish their tasks. 
    ONIXS_CONFLATEDUDP_LTWT_EXPORTED
    void 
    joinAll();
};

/// The collection of parameters affecting behavior 
/// of a thread pool. The given class serves as a base for 
/// defining and manipulating thread pool related parameters. 
ONIXS_CONFLATEDUDP_LTWT_CLASS 
ThreadPoolSettings
{
    ThreadAffinity affinity_;
    UInt32 size_;

public:
    /// Assigns the default values for the given 
    /// instance of the thread pool settings. 
    ThreadPoolSettings()
      : affinity_()
      , size_(1)
    {
    }

    /// Cleans everything up. 
    ~ThreadPoolSettings()
    {
    }

    /// Defines set of CPUs allowed for each working 
    /// thread to be executed on while running tasks. 
    ///
    /// @note By default set is empty thus allowing threads 
    /// to be executed on any CPU available in the system. 
    const 
    ThreadAffinity& 
    affinity() const
    {
        return affinity_;
    }

    /// Defines set of CPUs allowed for each working 
    /// thread to be executed on while running tasks. 
    ///
    /// @note By default set is empty thus allowing threads 
    /// to be executed on any CPU available in the system. 
    ThreadAffinity& affinity()
    {
        return affinity_;
    }

    /// Number of working threads in the pool.
    /// 
    /// @note Default value is '1'.
    UInt32 
    size() const
    {
        return size_;
    }

    /// Defines the number of working threads in the pool.
    void 
    size(
        UInt32 value)
    {
        size_ = value;
    }
};

/// Serializes thread pool settings into a string. 
ONIXS_CONFLATEDUDP_EXPORTED
void
toStr(
    std::string&,
    const 
    ThreadPoolSettings&);

/// Serializes thread pool settings into a string. 
inline 
std::string
toStr(
    const 
    ThreadPoolSettings& settings)
{
    std::string str;

    toStr(str, settings);

    return str;
}

ONIXS_CONFLATEDUDP_NAMESPACE_END