fiber/doc/queue.qbk

[/
          Copyright Oliver Kowalke 2013.
 Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
          http://www.boost.org/LICENSE_1_0.txt
]

[section:queues Queues]

__boost_fiber__ provides a bounded and a unbounded queue suitable to
synchonize fibers via message passing.

    typedef boost::fibers::unbounded_queue< int > queue_t;

    void send( queue_t & queue)
    {
        for ( int i = 0; i < 5; ++i)
            queue.put( i);
        queue.deactivate();
    }

    void recv( queue_t & queue)
    {
        boost::optional< int > value;
        while ( queue.take( value) )
        { std::cout << "received " << * value << std::endl; }
    }

    queue_t queue;
    boost::fibers::fiber s1(
        boost::fibers::spawn(
            boost::bind( send, ref( queue) ) ) );
    boost::fibers::fiber s2(
        boost::fibers::spawn(
            boost::bind( recv, ref( queue) ) ) );

    boost::fibers::waitfor_all( s1, s2);

[section:unbounded_queue Template `unbounded_queue`]

    #include <boost/fiber/unbounded_queue.hpp>

    template< typename T >
    class unbounded_queue
    {
    public:
        unbounded_queue( unbounded_queue const& other) = delete; 
        unbounded_queue & operator=( unbounded_queue const& other) = delete; 

        bool active() const;

        void deactivate();

        bool empty();

        void put( T const& t);

        bool take( boost::optional< T > & va);

        bool try_take( boost::optional< T > & va);
    };

[section:active Member function `active()`]

        bool active() const;

[variablelist
[[Effects:] [Return `true` if queue is still usable.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:deactivate Member function `deactivate()`]

        void deactivate();

[variablelist
[[Effects:] [Deactivates the queue. No values can be put after calling
`this->deactivate`. Strata blocked in `this->take()` will return.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:empty Member function `empty()`]

        bool empty();

[variablelist
[[Effects:] [Returns `true` if the queue currently contains no data.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:put Member function `put()`]

        void put( T const& t);

[variablelist
[[Effects:] [Enqueues the value in the queue and wakes up a fiber waiting
for new data available from the queue.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:take Member function `take()`]

        bool take( boost::optional< T > & va);

[variablelist
[[Effects:] [Dequeues a value from the queue. If no data is available from the
queue the fiber gets suspended until new data are enqueued (return value
`true` and va contains dequeued value) or the queue gets deactiveted and the
function returns `false`.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:try_take Member function `try_take()`]

        bool try_take( boost::optional< T > & va);

[variablelist
[[Effects:] [Dequeues a value from the queue. If no data is available from the
queue the function returns `false`. Otherwise it returns `true` and `va`
contains the dequed value.]]
[[Throws:] [Nothing.]]
]
[endsect]

[endsect]


[section:bounded_queue Template `bounded_queue`]

    #include <boost/fiber/bounded_queue.hpp>

    template< typename T >
    class bounded_queue
    {
    public:
        bounded_queue( bounded_queue const& other) = delete; 
        bounded_queue & operator=( bounded_queue const& other) = delete; 

        bounded_queue( std::size_t wm);

        bounded_queue( std::size_t hwm, std::size_t lwm);

        bool active() const;

        void deactivate();

        bool empty();

        void put( T const& t);

        bool take( boost::optional< T > & va);

        bool try_take( boost::optional< T > & va);
    };

[section:constructor Constructor]

        bounded_queue( std::size_t wm);
        bounded_queue( std::size_t hwm, std::size_t lwm);

[variablelist
[[Effects:] [Constructs an object of class `bounded_queue` which will contain
a maximum of `wm` items. The constructor with two arguments constructs an object
of class `bounded_queue` which will contain a high-watermark of `hwm` and a
low-watermark of `lwm` items.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:active Member function `active()`]

        bool active() const;

[variablelist
[[Effects:] [Return `true` if queue is still usable.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:deactivate Member function `deactivate()`]

        void deactivate();

[variablelist
[[Effects:] [Deactivates the queue. No values can be put after calling
`this->deactivate`. Strata blocked in `this->take()` will return.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:empty Member function `empty()`]

        bool empty();

[variablelist
[[Effects:] [Returns `true` if the queue currently contains no data.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:put Member function `put()`]

        void put( T const& t);

[variablelist
[[Effects:] [Enqueues the value in the queue and wakes up a fiber waiting
for new data available from the queue. If the watermark has reached the
fiber putting the value will be supended until at least one item was
dequeued.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:take Member fucntion `take()`]

        bool take( boost::optional< T > & va);

[variablelist
[[Effects:] [Dequeues a value from the queue. If no data is available from the
queue the fiber gets suspended until new data are enqueued (return value
`true` and va contains dequeued value) or the queue gets deactiveted and the
function returns `false`.]]
[[Throws:] [Nothing.]]
]
[endsect]

[section:try_take Member function `try_take()`]

        bool try_take( boost::optional< T > & va);

[variablelist
[[Effects:] [Dequeues a value from the queue. If no data is available from the
queue the function returns `false`. Otherwise it returns `true` and `va`
contains the dequed value.]]
[[Throws:] [Nothing.]]
]
[endsect]

[endsect]

[endsect]