.rst .pdf

open issue suggest edit

Contents

enumerable_thread_specific

[tls.enumerable_thread_specific]

A class template for thread local storage (TLS).

// Defined in header <oneapi/tbb/enumerable_thread_specific.h>

namespace oneapi {
namespace tbb {

    enum ets_key_usage_type {
        ets_key_per_instance,
        ets_no_key,
        ets_suspend_aware
    };

    template <typename T,
        typename Allocator=cache_aligned_allocator<T>,
        ets_key_usage_type ETS_key_type=ets_no_key >
    class enumerable_thread_specific {
    public:
        // Basic types
        using value_type = T;
        using reference = T&;
        using const_reference = const T&;
        using pointer = T*;
        using size_type = /* implementation-defined */;
        using difference_type = /* implementation-defined */;
        using allocator_type = Allocator;

        // Iterator types
        using iterator = /* implementation-defined */;
        using const_iterator = /* implementation-defined */;

        // Parallel range types
        using range_type = /* implementation-defined */;
        using const_range_type = /* implementation-defined */;

        // Construction
        enumerable_thread_specific();
        template <typename Finit>
        explicit enumerable_thread_specific( Finit finit );
        explicit enumerable_thread_specific( const T& exemplar );
        explicit enumerable_thread_specific( T&& exemplar );
        template <typename... Args>
        enumerable_thread_specific( Args&&... args );

        // Destruction
        ~enumerable_thread_specific();

        // Copy constructors
        enumerable_thread_specific( const enumerable_thread_specific& other);
        template<typename Alloc, ets_key_usage_type Cachetype>
        enumerable_thread_specific( const enumerable_thread_specific<T, Alloc, Cachetype>& other);
        // Copy assignments
        enumerable_thread_specific& operator=( const enumerable_thread_specific& other );
        template<typename Alloc, ets_key_usage_type Cachetype>
        enumerable_thread_specific& operator=( const enumerable_thread_specific<T, Alloc, Cachetype>& other );

        // Move constructors
        enumerable_thread_specific( enumerable_thread_specific&& other);
        template<typename Alloc, ets_key_usage_type Cachetype>
        enumerable_thread_specific( enumerable_thread_specific<T, Alloc, Cachetype>&& other);
        // Move assignments
        enumerable_thread_specific& operator=( enumerable_thread_specific&& other );
        template<typename Alloc, ets_key_usage_type Cachetype>
        enumerable_thread_specific& operator=( enumerable_thread_specific<T, Alloc, Cachetype>&& other );

        // Other whole container operations
        void clear();

        // Concurrent operations
        reference local();
        reference local( bool& exists );
        size_type size() const;
        bool empty() const;

        // Combining
        template<typename BinaryFunc> T combine( BinaryFunc f );
        template<typename UnaryFunc> void combine_each( UnaryFunc f );

        // Parallel iteration
        range_type range( size_t grainsize=1 );
        const_range_type range( size_t grainsize=1 ) const;

        // Iterators
        iterator begin();
        iterator end();
        const_iterator begin() const;
        const_iterator end() const;
    };

} // namespace tbb
} // namespace oneapi

A class template enumerable_thread_specific provides TLS for elements of type T. A class template enumerable_thread_specific acts as a container by providing iterators and ranges across all of the thread-local elements.

The thread-local elements are created lazily. A freshly constructed enumerable_thread_specific has no elements. When a thread requests access to an enumerable_thread_specific, it creates an element corresponding to that thread. The number of elements is equal to the number of distinct threads that have accessed the enumerable_thread_specific and not necessarily the number of threads in use by the application. Clearing an enumerable_thread_specific removes all its elements.

Use the ETS_key_usage_type parameter type to select an underlying implementation.

Caution

enumerable_thread_specific uses the OS-specific value returned by std::this_thread::get_id() to identify threads. This value is not guaranteed to be unique except for the life of the thread. A newly created thread may get an OS-specific ID equal to that of an already destroyed thread. The number of elements of the enumerable_thread_specific may therefore be less than the number of actual distinct threads that have called local(), and the element returned by the first reference by a thread to the enumerable_thread_specific may not be newly-constructed.

Member functions

• Construction, destruction, copying
• Concurrently safe modifiers
• Concurrently unsafe modifiers
• Size and capacity
• Iteration
• Combining

Non-member types and constants

enum ets_key_usage_type::ets_key_per_instance

Enumeration parameter type used to select an implementation that consumes 1 native TLS key per enumerable_thread_specific instance. The number of native TLS keys may be limited and can be fairly small.

enum ets_key_usage_type::ets_no_key

Enumeration parameter type used to select an implementation that consumes no native TLS keys. If no ETS_key_usage_type parameter type is provided, ets_no_key is used by default.

enum ets_key_usage_type::ets_suspend_aware

The oneapi::tbb::task::suspend function can change the value of the enumerable_thread_specific object. To avoid this problem, use the ets_suspend_aware enumeration parameter type. The local() value can be the same for different threads, but no two distinct threads can access the same value simultaneously.

previous

combinable

next

Construction, destruction, copying