Intel(R) Threading Building Blocks Doxygen Documentation  version 4.2.3
tbb::interface6::aggregator_ext< handler_type > Class Template Reference

Aggregator base class and expert interface. More...

#include <aggregator.h>

Inheritance diagram for tbb::interface6::aggregator_ext< handler_type >:
Collaboration diagram for tbb::interface6::aggregator_ext< handler_type >:

Public Member Functions

 aggregator_ext (const handler_type &h)
 
void process (aggregator_operation *op)
 EXPERT INTERFACE: Enter a user-made operation into the aggregator's mailbox. More...
 

Protected Member Functions

void execute_impl (aggregator_operation &op)
 

Private Member Functions

void start_handle_operations ()
 Trigger the handling of operations when the handler is free. More...
 
- Private Member Functions inherited from tbb::internal::no_copy
 no_copy ()
 Allow default construction. More...
 

Private Attributes

atomic< aggregator_operation * > mailbox
 An atomically updated list (aka mailbox) of aggregator_operations. More...
 
uintptr_t handler_busy
 Controls thread access to handle_operations. More...
 
handler_type handle_operations
 

Detailed Description

template<typename handler_type>
class tbb::interface6::aggregator_ext< handler_type >

Aggregator base class and expert interface.

An aggregator for collecting operations coming from multiple sources and executing them serially on a single thread.

Definition at line 97 of file aggregator.h.

Constructor & Destructor Documentation

◆ aggregator_ext()

template<typename handler_type>
tbb::interface6::aggregator_ext< handler_type >::aggregator_ext ( const handler_type &  h)
inline

Definition at line 99 of file aggregator.h.

99 : handler_busy(0), handle_operations(h) { mailbox = NULL; }
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 h
atomic< aggregator_operation * > mailbox
An atomically updated list (aka mailbox) of aggregator_operations.
Definition: aggregator.h:140
uintptr_t handler_busy
Controls thread access to handle_operations.
Definition: aggregator.h:144

Member Function Documentation

◆ execute_impl()

template<typename handler_type>
void tbb::interface6::aggregator_ext< handler_type >::execute_impl ( aggregator_operation op)
inlineprotected

Place operation in mailbox, then either handle mailbox or wait for the operation to be completed by a different thread.

Definition at line 108 of file aggregator.h.

108  {
109  aggregator_operation* res;
110 
111  // ITT note: &(op.status) tag is used to cover accesses to this operation. This
112  // thread has created the operation, and now releases it so that the handler
113  // thread may handle the associated operation w/o triggering a race condition;
114  // thus this tag will be acquired just before the operation is handled in the
115  // handle_operations functor.
116  call_itt_notify(releasing, &(op.status));
117  // insert the operation into the list
118  do {
119  // ITT may flag the following line as a race; it is a false positive:
120  // This is an atomic read; we don't provide itt_hide_load_word for atomics
121  op.my_next = res = mailbox; // NOT A RACE
122  } while (mailbox.compare_and_swap(&op, res) != res);
123  if (!res) { // first in the list; handle the operations
124  // ITT note: &mailbox tag covers access to the handler_busy flag, which this
125  // waiting handler thread will try to set before entering handle_operations.
128  __TBB_ASSERT(op.status, NULL);
129  }
130  else { // not first; wait for op to be ready
131  call_itt_notify(prepare, &(op.status));
133  itt_load_word_with_acquire(op.status);
134  }
135  }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
atomic< aggregator_operation * > mailbox
An atomically updated list (aka mailbox) of aggregator_operations.
Definition: aggregator.h:140
T itt_load_word_with_acquire(const tbb::atomic< T > &src)
void spin_wait_while_eq(const volatile T &location, U value)
Spin WHILE the value of the variable is equal to a given value.
Definition: tbb_machine.h:395
void start_handle_operations()
Trigger the handling of operations when the handler is free.
Definition: aggregator.h:149
void call_itt_notify(notify_type, void *)

◆ process()

template<typename handler_type>
void tbb::interface6::aggregator_ext< handler_type >::process ( aggregator_operation op)
inline

EXPERT INTERFACE: Enter a user-made operation into the aggregator's mailbox.

Details of user-made operations must be handled by user-provided handler

Definition at line 103 of file aggregator.h.

103 { execute_impl(*op); }
void execute_impl(aggregator_operation &op)
Definition: aggregator.h:108

◆ start_handle_operations()

template<typename handler_type>
void tbb::interface6::aggregator_ext< handler_type >::start_handle_operations ( )
inlineprivate

Trigger the handling of operations when the handler is free.

Definition at line 149 of file aggregator.h.

149  {
150  aggregator_operation *pending_operations;
151 
152  // ITT note: &handler_busy tag covers access to mailbox as it is passed
153  // between active and waiting handlers. Below, the waiting handler waits until
154  // the active handler releases, and the waiting handler acquires &handler_busy as
155  // it becomes the active_handler. The release point is at the end of this
156  // function, when all operations in mailbox have been handled by the
157  // owner of this aggregator.
159  // get handler_busy: only one thread can possibly spin here at a time
160  spin_wait_until_eq(handler_busy, uintptr_t(0));
162  // acquire fence not necessary here due to causality rule and surrounding atomics
163  __TBB_store_with_release(handler_busy, uintptr_t(1));
164 
165  // ITT note: &mailbox tag covers access to the handler_busy flag itself.
166  // Capturing the state of the mailbox signifies that handler_busy has been
167  // set and a new active handler will now process that list's operations.
169  // grab pending_operations
170  pending_operations = mailbox.fetch_and_store(NULL);
171 
172  // handle all the operations
173  handle_operations(pending_operations);
174 
175  // release the handler
177  }
atomic< aggregator_operation * > mailbox
An atomically updated list (aka mailbox) of aggregator_operations.
Definition: aggregator.h:140
void itt_store_word_with_release(tbb::atomic< T > &dst, U src)
void call_itt_notify(notify_type, void *)
void spin_wait_until_eq(const volatile T &location, const U value)
Spin UNTIL the value of the variable is equal to a given value.
Definition: tbb_machine.h:403
uintptr_t handler_busy
Controls thread access to handle_operations.
Definition: aggregator.h:144
void __TBB_store_with_release(volatile T &location, V value)
Definition: tbb_machine.h:717

Member Data Documentation

◆ handle_operations

template<typename handler_type>
handler_type tbb::interface6::aggregator_ext< handler_type >::handle_operations
private

Definition at line 146 of file aggregator.h.

◆ handler_busy

template<typename handler_type>
uintptr_t tbb::interface6::aggregator_ext< handler_type >::handler_busy
private

Controls thread access to handle_operations.

Behaves as boolean flag where 0=false, 1=true

Definition at line 144 of file aggregator.h.

◆ mailbox

template<typename handler_type>
atomic<aggregator_operation *> tbb::interface6::aggregator_ext< handler_type >::mailbox
private

An atomically updated list (aka mailbox) of aggregator_operations.

Definition at line 140 of file aggregator.h.


The documentation for this class was generated from the following file:

Copyright © 2005-2019 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.