...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Boost.Fiber provides a bounded, buffered channel (MPMC queue) suitable to synchonize fibers (running on same or different threads) via asynchronouss message passing.
typedef boost::fibers::buffered_channel< int > channel_t; void send( channel_t & chan) { for ( int i = 0; i < 5; ++i) { chan.push( i); } chan.close(); } void recv( channel_t & chan) { int i; while ( boost::fibers::channel_op_status::success == chan.pop(i) ) { std::cout << "received " << i << std::endl; } } channel_t chan{ 2 }; boost::fibers::fiber f1( std::bind( send, std::ref( chan) ) ); boost::fibers::fiber f2( std::bind( recv, std::ref( chan) ) ); f1.join(); f2.join();
Class buffered_channel
supports range-for syntax:
typedef boost::fibers::buffered_channel< int > channel_t; void foo( channel_t & chan) { chan.push( 1); chan.push( 1); chan.push( 2); chan.push( 3); chan.push( 5); chan.push( 8); chan.push( 12); chan.close(); } void bar( channel_t & chan) { for ( unsigned int value : chan) { std::cout << value << " "; } std::cout << std::endl; }
buffered_channel<>
#include <boost/fiber/buffered_channel.hpp> namespace boost { namespace fibers { template< typename T > class buffered_channel { public: typedef T value_type; class iterator; explicit buffered_channel( std::size_t capacity); buffered_channel( buffered_channel const& other) = delete; buffered_channel & operator=( buffered_channel const& other) = delete; void close() noexcept; channel_op_status push( value_type const& va); channel_op_status push( value_type && va); template< typename Rep, typename Period > channel_op_status push_wait_for( value_type const& va, std::chrono::duration< Rep, Period > const& timeout_duration); channel_op_status push_wait_for( value_type && va, std::chrono::duration< Rep, Period > const& timeout_duration); template< typename Clock, typename Duration > channel_op_status push_wait_until( value_type const& va, std::chrono::time_point< Clock, Duration > const& timeout_time); template< typename Clock, typename Duration > channel_op_status push_wait_until( value_type && va, std::chrono::time_point< Clock, Duration > const& timeout_time); channel_op_status try_push( value_type const& va); channel_op_status try_push( value_type && va); channel_op_status pop( value_type & va); value_type value_pop(); template< typename Rep, typename Period > channel_op_status pop_wait_for( value_type & va, std::chrono::duration< Rep, Period > const& timeout_duration); template< typename Clock, typename Duration > channel_op_status pop_wait_until( value_type & va, std::chrono::time_point< Clock, Duration > const& timeout_time); channel_op_status try_pop( value_type & va); }; template< typename T > buffered_channel< T >::iterator begin( buffered_channel< T > & chan); template< typename T > buffered_channel< T >::iterator end( buffered_channel< T > & chan); }}
explicit buffered_channel( std::size_t capacity);
2<=capacity &&
0==(capacity &
(capacity-1))
The constructor constructs an object of class buffered_channel
with an internal buffer of size capacity
.
fiber_error
invalid_argument: if 0==capacity ||
0!=(capacity &
(capacity-1))
.
A push()
,
push_wait_for()
or push_wait_until()
will not block until the number
of values in the channel becomes equal to capacity
.
The channel can hold only capacity
- 1
elements, otherwise it is considered to be full.
close
()
void close() noexcept;
Deactivates the channel. No values can be put after calling this->close()
.
Fibers blocked in this->pop()
, this->pop_wait_for()
or this->pop_wait_until()
will return closed
.
Fibers blocked in this->value_pop()
will receive an exception.
Nothing.
close()
is like closing a pipe. It informs waiting consumers that no more
values will arrive.
push
()
channel_op_status push( value_type const& va); channel_op_status push( value_type && va);
If channel is closed, returns closed
.
Otherwise enqueues the value in the channel, wakes up a fiber blocked
on this->pop()
,
this->value_pop()
,
this->pop_wait_for()
or this->pop_wait_until()
and returns success
.
If the channel is full, the fiber is blocked.
Exceptions thrown by copy- or move-operations.
try_push
()
channel_op_status try_push( value_type const& va); channel_op_status try_push( value_type && va);
If channel is closed, returns closed
.
Otherwise enqueues the value in the channel, wakes up a fiber blocked
on this->pop()
,
this->value_pop()
,
this->pop_wait_for()
or this->pop_wait_until()
and returns success
.
If the channel is full, it doesn't block and returns full
.
Exceptions thrown by copy- or move-operations.
pop
()
channel_op_status pop( value_type & va);
Dequeues a value from the channel. If the channel is empty, the fiber
gets suspended until at least one new item is push()
ed (return value success
and va
contains dequeued
value) or the channel gets close()
d (return value closed
).
Exceptions thrown by copy- or move-operations.
value_pop
()
value_type value_pop();
Dequeues a value from the channel. If the channel is empty, the fiber
gets suspended until at least one new item is push()
ed or the channel gets close()
d
(which throws an exception).
fiber_error
if *this
is closed or by copy- or move-operations.
std::errc::operation_not_permitted
try_pop
()
channel_op_status try_pop( value_type & va);
If channel is empty, returns empty
.
If channel is closed, returns closed
.
Otherwise it returns success
and va
contains the
dequeued value.
Exceptions thrown by copy- or move-operations.
pop_wait_for
()
template< typename Rep, typename Period > channel_op_status pop_wait_for( value_type & va, std::chrono::duration< Rep, Period > const& timeout_duration)
Accepts std::chrono::duration
and internally computes
a timeout time as (system time + timeout_duration
).
If channel is not empty, immediately dequeues a value from the channel.
Otherwise the fiber gets suspended until at least one new item is
push()
ed
(return value success
and va
contains dequeued
value), or the channel gets close()
d (return value closed
),
or the system time reaches the computed timeout time (return value
timeout
).
timeout-related exceptions or by copy- or move-operations.
pop_wait_until
()
template< typename Clock, typename Duration > channel_op_status pop_wait_until( value_type & va, std::chrono::time_point< Clock, Duration > const& timeout_time)
Accepts a std::chrono::time_point<
Clock,
Duration >
.
If channel is not empty, immediately dequeues a value from the channel.
Otherwise the fiber gets suspended until at least one new item is
push()
ed
(return value success
and va
contains dequeued
value), or the channel gets close()
d (return value closed
),
or the system time reaches the passed time_point
(return value timeout
).
timeout-related exceptions or by copy- or move-operations.
begin(
buffered_channel<
T >
&)
template< typename T > buffered_channel< T >::iterator begin( buffered_channel< T > &);
Returns a range-iterator (input-iterator).
end(
buffered_channel<
T >
&)
template< typename T > buffered_channel< R >::iterator end( buffered_channel< T > &);
Returns an end range-iterator (input-iterator).