mailbox.h
Go to the documentation of this file.
/*
Copyright (c) 2005-2020 Intel Corporation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
#ifndef _TBB_mailbox_H
#define _TBB_mailbox_H
#include "tbb/tbb_stddef.h"
#include "tbb/cache_aligned_allocator.h"
#include "scheduler_common.h"
#include "tbb/atomic.h"
namespace tbb {
namespace internal {
struct task_proxy : public task {
static const intptr_t pool_bit = 1<<0;
static const intptr_t mailbox_bit = 1<<1;
static const intptr_t location_mask = pool_bit | mailbox_bit;
/* All but two low-order bits represent a (task*).
Two low-order bits mean:
1 = proxy is/was/will be in task pool
2 = proxy is/was/will be in mailbox */
intptr_t task_and_tag;
task_proxy *__TBB_atomic next_in_mailbox;
mail_outbox* outbox;
static bool is_shared ( intptr_t tat ) {
return (tat & location_mask) == location_mask;
}
static task* task_ptr ( intptr_t tat ) {
return (task*)(tat & ~location_mask);
}
template<intptr_t from_bit>
inline task* extract_task () {
__TBB_ASSERT( prefix().extra_state == es_task_proxy, "Normal task misinterpreted as a proxy?" );
intptr_t tat = __TBB_load_with_acquire(task_and_tag);
__TBB_ASSERT( tat == from_bit || (is_shared(tat) && task_ptr(tat)),
"Proxy's tag cannot specify both locations if the proxy "
"was retrieved from one of its original locations" );
if ( tat != from_bit ) {
const intptr_t cleaner_bit = location_mask & ~from_bit;
// Attempt to transition the proxy to the "empty" state with
// cleaner_bit specifying entity responsible for its eventual freeing.
// Explicit cast to void* is to work around a seeming ICC 11.1 bug.
if ( as_atomic(task_and_tag).compare_and_swap(cleaner_bit, tat) == tat ) {
// Successfully grabbed the task, and left new owner with the job of freeing the proxy
return task_ptr(tat);
}
}
// Proxied task has already been claimed from another proxy location.
__TBB_ASSERT( task_and_tag == from_bit, "Empty proxy cannot contain non-zero task pointer" );
return NULL;
}
}; // struct task_proxy
class unpadded_mail_outbox {
protected:
typedef task_proxy*__TBB_atomic proxy_ptr;
proxy_ptr my_first;
proxy_ptr* __TBB_atomic my_last;
bool my_is_idle;
};
class mail_outbox : padded<unpadded_mail_outbox> {
task_proxy* internal_pop( __TBB_ISOLATION_EXPR(isolation_tag isolation) ) {
task_proxy* curr = __TBB_load_relaxed( my_first );
if ( !curr )
return NULL;
task_proxy **prev_ptr = &my_first;
#if __TBB_TASK_ISOLATION
if ( isolation != no_isolation ) {
while ( curr->prefix().isolation != isolation ) {
prev_ptr = &curr->next_in_mailbox;
curr = curr->next_in_mailbox;
if ( !curr )
return NULL;
}
}
#endif /* __TBB_TASK_ISOLATION */
__TBB_control_consistency_helper(); // on my_first
// There is a first item in the mailbox. See if there is a second.
if ( task_proxy* second = curr->next_in_mailbox ) {
// There are at least two items, so first item can be popped easily.
*prev_ptr = second;
} else {
// There is only one item. Some care is required to pop it.
*prev_ptr = NULL;
if ( as_atomic( my_last ).compare_and_swap( prev_ptr, &curr->next_in_mailbox ) == &curr->next_in_mailbox ) {
// Successfully transitioned mailbox from having one item to having none.
__TBB_ASSERT( !curr->next_in_mailbox, NULL );
} else {
// Some other thread updated my_last but has not filled in first->next_in_mailbox
// Wait until first item points to second item.
atomic_backoff backoff;
while ( !(second = curr->next_in_mailbox) ) backoff.pause();
*prev_ptr = second;
}
}
__TBB_ASSERT( curr, NULL );
return curr;
}
public:
friend class mail_inbox;
void push( task_proxy* t ) {
__TBB_ASSERT(t, NULL);
t->next_in_mailbox = NULL;
proxy_ptr * const link = (proxy_ptr *)__TBB_FetchAndStoreW(&my_last,(intptr_t)&t->next_in_mailbox);
// No release fence required for the next store, because there are no memory operations
// between the previous fully fenced atomic operation and the store.
__TBB_store_relaxed(*link, t);
}
bool empty() {
return __TBB_load_relaxed(my_first) == NULL;
}
void construct() {
__TBB_ASSERT( sizeof(*this)==NFS_MaxLineSize, NULL );
__TBB_ASSERT( !my_first, NULL );
__TBB_ASSERT( !my_last, NULL );
__TBB_ASSERT( !my_is_idle, NULL );
my_last=&my_first;
suppress_unused_warning(pad);
}
intptr_t drain() {
intptr_t k = 0;
// No fences here because other threads have already quit.
for( ; task_proxy* t = my_first; ++k ) {
my_first = t->next_in_mailbox;
NFS_Free((char*)t - task_prefix_reservation_size);
}
return k;
}
bool recipient_is_idle() {
return my_is_idle;
}
}; // class mail_outbox
class mail_inbox {
mail_outbox* my_putter;
public:
mail_inbox() : my_putter(NULL) {}
void attach( mail_outbox& putter ) {
my_putter = &putter;
}
void detach() {
__TBB_ASSERT(my_putter,"not attached");
my_putter = NULL;
}
task_proxy* pop( __TBB_ISOLATION_EXPR( isolation_tag isolation ) ) {
return my_putter->internal_pop( __TBB_ISOLATION_EXPR( isolation ) );
}
bool empty() {
return my_putter->empty();
}
void set_is_idle( bool value ) {
if( my_putter ) {
__TBB_ASSERT( my_putter->my_is_idle || value, "attempt to redundantly mark mailbox as not idle" );
my_putter->my_is_idle = value;
}
}
bool is_idle_state ( bool value ) const {
return !my_putter || my_putter->my_is_idle == value;
}
#if DO_ITT_NOTIFY
void* outbox() const {return my_putter;}
#endif /* DO_ITT_NOTIFY */
}; // class mail_inbox
} // namespace internal
} // namespace tbb
#endif /* _TBB_mailbox_H */
tbb::internal::task_proxy::task_ptr
static task * task_ptr(intptr_t tat)
Returns a pointer to the encapsulated task or NULL.
Definition: mailbox.h:51
tbb::task::prefix
internal::task_prefix & prefix(internal::version_tag *=NULL) const
Get reference to corresponding task_prefix.
Definition: task.h:991
tbb::internal::padded
Pads type T to fill out to a multiple of cache line size.
Definition: tbb_stddef.h:261
scheduler_common.h
tbb::internal::__TBB_load_with_acquire
T __TBB_load_with_acquire(const volatile T &location)
Definition: tbb_machine.h:712
tbb::internal::mail_inbox::pop
task_proxy * pop(__TBB_ISOLATION_EXPR(isolation_tag isolation))
Get next piece of mail, or NULL if mailbox is empty.
Definition: mailbox.h:202
tbb::internal::task_proxy::pool_bit
static const intptr_t pool_bit
Definition: mailbox.h:30
internal
Definition: _flow_graph_async_msg_impl.h:24
tbb::internal::task_proxy::is_shared
static bool is_shared(intptr_t tat)
True if the proxy is stored both in its sender's pool and in the destination mailbox.
Definition: mailbox.h:46
tbb::internal::task_proxy::task_and_tag
intptr_t task_and_tag
Definition: mailbox.h:37
tbb::internal::mail_outbox::push
void push(task_proxy *t)
Push task_proxy onto the mailbox queue of another thread.
Definition: mailbox.h:140
__TBB_ISOLATION_EXPR
#define __TBB_ISOLATION_EXPR(isolation)
Definition: scheduler_common.h:67
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
tbb::internal::mail_inbox::empty
bool empty()
Return true if mailbox is empty.
Definition: mailbox.h:206
tbb::internal::atomic_backoff
Class that implements exponential backoff.
Definition: tbb_machine.h:348
cache_aligned_allocator.h
tbb
The graph class.
Definition: serial/tbb/parallel_for.h:46
tbb::internal::padded_base< unpadded_mail_outbox, NFS_MaxLineSize, sizeof(unpadded_mail_outbox) % NFS_MaxLineSize >::pad
char pad[S - R]
Definition: tbb_stddef.h:255
tbb::internal::es_task_proxy
Tag for v3 task_proxy.
Definition: scheduler_common.h:174
tbb::internal::mail_inbox
Class representing source of mail.
Definition: mailbox.h:185
tbb::internal::mail_inbox::is_idle_state
bool is_idle_state(bool value) const
Indicate whether thread that reads this mailbox is idle.
Definition: mailbox.h:218
tbb::internal::unpadded_mail_outbox::proxy_ptr
task_proxy *__TBB_atomic proxy_ptr
Definition: mailbox.h:82
tbb::internal::mail_outbox::empty
bool empty()
Return true if mailbox is empty.
Definition: mailbox.h:150
tbb::internal::mail_inbox::mail_inbox
mail_inbox()
Construct unattached inbox.
Definition: mailbox.h:190
tbb::internal::unpadded_mail_outbox
Internal representation of mail_outbox, without padding.
Definition: mailbox.h:80
tbb::internal::mail_outbox::recipient_is_idle
bool recipient_is_idle()
True if thread that owns this mailbox is looking for work.
Definition: mailbox.h:179
tbb::internal::unpadded_mail_outbox::my_last
proxy_ptr *__TBB_atomic my_last
Pointer to pointer that will point to next item in the queue. Never NULL.
Definition: mailbox.h:88
tbb::internal::unpadded_mail_outbox::my_is_idle
bool my_is_idle
Owner of mailbox is not executing a task, and has drained its own task pool.
Definition: mailbox.h:91
tbb::internal::atomic_backoff::pause
void pause()
Pause for a while.
Definition: tbb_machine.h:363
__TBB_atomic
#define __TBB_atomic
Definition: tbb_stddef.h:237
tbb::internal::mail_outbox::internal_pop
task_proxy * internal_pop(__TBB_ISOLATION_EXPR(isolation_tag isolation))
Definition: mailbox.h:98
tbb::internal::mail_outbox::drain
intptr_t drain()
Drain the mailbox.
Definition: mailbox.h:168
tbb::internal::task_proxy::mailbox_bit
static const intptr_t mailbox_bit
Definition: mailbox.h:31
tbb::internal::mail_inbox::attach
void attach(mail_outbox &putter)
Attach inbox to a corresponding outbox.
Definition: mailbox.h:193
tbb::internal::mail_inbox::my_putter
mail_outbox * my_putter
Corresponding sink where mail that we receive will be put.
Definition: mailbox.h:187
tbb::internal::__TBB_store_relaxed
void __TBB_store_relaxed(volatile T &location, V value)
Definition: tbb_machine.h:742
tbb::internal::task_proxy::extract_task
task * extract_task()
Returns a pointer to the encapsulated task or NULL, and frees proxy if necessary.
Definition: mailbox.h:57
tbb::internal::task_proxy::location_mask
static const intptr_t location_mask
Definition: mailbox.h:32
tbb::internal::no_isolation
const isolation_tag no_isolation
Definition: task.h:133
atomic.h
tbb::internal::mail_inbox::detach
void detach()
Detach inbox from its outbox.
Definition: mailbox.h:197
tbb::internal::mail_inbox::set_is_idle
void set_is_idle(bool value)
Indicate whether thread that reads this mailbox is idle.
Definition: mailbox.h:211
tbb::internal::NFS_MaxLineSize
const size_t NFS_MaxLineSize
Compile-time constant that is upper bound on cache line/sector size.
Definition: tbb_stddef.h:216
__TBB_control_consistency_helper
#define __TBB_control_consistency_helper()
Definition: gcc_generic.h:60
tbb::internal::isolation_tag
intptr_t isolation_tag
A tag for task isolation.
Definition: task.h:132
tbb::internal::suppress_unused_warning
void suppress_unused_warning(const T1 &)
Utility template function to prevent "unused" warnings by various compilers.
Definition: tbb_stddef.h:398
tbb::internal::mail_outbox::construct
void construct()
Construct *this as a mailbox from zeroed memory.
Definition: mailbox.h:158
tbb::internal::mail_outbox
Class representing where mail is put.
Definition: mailbox.h:96
tbb::internal::as_atomic
atomic< T > & as_atomic(T &t)
Definition: atomic.h:572
tbb::internal::task_prefix::isolation
isolation_tag isolation
The tag used for task isolation.
Definition: task.h:209
value
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p void ITT_FORMAT p no args __itt_suppress_mode_t unsigned int void size_t ITT_FORMAT d void ITT_FORMAT p void ITT_FORMAT p __itt_model_site __itt_model_site_instance ITT_FORMAT p __itt_model_task __itt_model_task_instance ITT_FORMAT p void ITT_FORMAT p void ITT_FORMAT p void size_t ITT_FORMAT d void ITT_FORMAT p const wchar_t ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s const char ITT_FORMAT s no args void ITT_FORMAT p size_t ITT_FORMAT d no args const wchar_t const wchar_t ITT_FORMAT s __itt_heap_function void size_t int ITT_FORMAT d __itt_heap_function void ITT_FORMAT p __itt_heap_function void void size_t int ITT_FORMAT d no args no args unsigned int ITT_FORMAT u const __itt_domain __itt_id ITT_FORMAT lu const __itt_domain __itt_id __itt_id __itt_string_handle ITT_FORMAT p const __itt_domain __itt_id ITT_FORMAT p const __itt_domain __itt_id __itt_timestamp __itt_timestamp ITT_FORMAT lu const __itt_domain __itt_id __itt_id __itt_string_handle ITT_FORMAT p const __itt_domain ITT_FORMAT p const __itt_domain __itt_string_handle unsigned long long value
Definition: ittnotify_static.h:192
tbb::task
Base class for user-defined tasks.
Definition: task.h:604
tbb_stddef.h
tbb::internal::NFS_Free
void __TBB_EXPORTED_FUNC NFS_Free(void *)
Free memory allocated by NFS_Allocate.
Definition: cache_aligned_allocator.cpp:198
tbb::internal::unpadded_mail_outbox::my_first
proxy_ptr my_first
Pointer to first task_proxy in mailbox, or NULL if box is empty.
Definition: mailbox.h:85
tbb::internal::task_proxy
Definition: mailbox.h:29
tbb::internal::task_prefix_reservation_size
const size_t task_prefix_reservation_size
Number of bytes reserved for a task prefix.
Definition: scheduler_common.h:159
tbb::internal::task_proxy::next_in_mailbox
task_proxy *__TBB_atomic next_in_mailbox
Pointer to next task_proxy in a mailbox.
Definition: mailbox.h:40
tbb::internal::task_proxy::outbox
mail_outbox * outbox
Mailbox to which this was mailed.
Definition: mailbox.h:43
tbb::internal::__TBB_load_relaxed
T __TBB_load_relaxed(const volatile T &location)
Definition: tbb_machine.h:738

Copyright © 2005-2020 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.