[Boost-commit] svn:boost r85318 - trunk/libs/coroutine/doc

Subject: [Boost-commit] svn:boost r85318 - trunk/libs/coroutine/doc
From: oliver.kowalke_at_[hidden]
Date: 2013-08-12 09:23:35

Author: olli
Date: 2013-08-12 09:23:35 EDT (Mon, 12 Aug 2013)
New Revision: 85318
URL: http://svn.boost.org/trac/boost/changeset/85318

Log:
coroutine: add example to documentation

Text files modified: 
   trunk/libs/coroutine/doc/motivation.qbk |   129 ++++++++++++++++++++++++++++++++++++++++
   1 files changed, 129 insertions(+), 0 deletions(-)

Modified: trunk/libs/coroutine/doc/motivation.qbk
==============================================================================
--- trunk/libs/coroutine/doc/motivation.qbk	Mon Aug 12 08:19:29 2013	(r85317)
+++ trunk/libs/coroutine/doc/motivation.qbk	2013-08-12 09:23:35 EDT (Mon, 12 Aug 2013)	(r85318)
@@ -157,6 +157,135 @@
         Done
 
 
+[heading chaining coroutines]
+
+The following example demonstrates how coroutines could be chained.
+
+        typedef boost::coroutines::coroutine<std::string> coro_t;
+
+        // deliver each line of input stream to sink as a separate string
+        void readlines(coro_t::push_type& sink, std::istream& in){
+            std::string line;
+            while(std::getline(in,line))
+                sink(line);
+        }
+
+        void tokenize(coro_t::push_type& sink, coro_t::pull_type& source){
+            // This tokenizer doesn't happen to be stateful: you could reasonably
+            // implement it with a single call to push each new token downstream. But
+            // I've worked with stateful tokenizers, in which the meaning of input
+            // characters depends in part on their position within the input line.
+            BOOST_FOREACH(std::string line, source){
+                std::string::size_type pos = 0;
+                while(pos < line.length()){
+                    if (line[pos] == '"'){
+                        std::string token;
+                        ++pos;              // skip open quote
+                        while (pos < line.length() && line[pos] != '"')
+                            token += line[pos++];
+                        ++pos;              // skip close quote
+                        sink(token);        // pass token downstream
+                    } else if (std::isspace(line[pos])){
+                        ++pos;              // outside quotes, ignore whitespace
+                    } else if (std::isalpha(line[pos])){
+                        std::string token;
+                        while (pos < line.length() && std::isalpha(line[pos]))
+                            token += line[pos++];
+                        sink(token);        // pass token downstream
+                    } else {                // punctuation
+                        sink(std::string(1,line[pos++]));
+                    }
+                }
+            }
+        }
+
+        void only_words(coro_t::push_type& sink,coro_t::pull_type& source){
+            BOOST_FOREACH(std::string token,source){
+                if (!token.empty() && std::isalpha(token[0]))
+                    sink(token);
+            }
+        }
+
+        void trace(coro_t::push_type& sink, coro_t::pull_type& source){
+            BOOST_FOREACH(std::string token,source){
+                std::cout << "trace: '" << token << "'\n";
+                sink(token);
+            }
+        }
+
+        struct FinalEOL{
+            ~FinalEOL(){
+                std::cout << std::endl;
+            }
+        };
+
+        void layout(coro_t::pull_type& source,int num,int width){
+            // Finish the last line when we leave by whatever means
+            FinalEOL eol;
+
+            // Pull values from upstream, lay them out 'num' to a line
+            for (;;){
+                for (int i = 0; i < num; ++i){
+                    // when we exhaust the input, stop
+                    if (!source) return;
+
+                    std::cout << std::setw(width) << source.get();
+                    // now that we've handled this item, advance to next
+                    source();
+                }
+                // after 'num' items, line break
+                std::cout << std::endl;
+            }
+        }
+
+        // For example purposes, instead of having a separate text file in the
+        // local filesystem, construct an istringstream to read.
+        std::string data(
+            "This is the first line.\n"
+            "This, the second.\n"
+            "The third has \"a phrase\"!\n"
+            );
+
+        {
+            std::cout << "\nfilter:\n";
+            std::istringstream infile(data);
+            coro_t::pull_type reader(boost::bind(readlines, _1, boost::ref(infile)));
+            coro_t::pull_type tokenizer(boost::bind(tokenize, _1, boost::ref(reader)));
+            coro_t::pull_type filter(boost::bind(only_words, _1, boost::ref(tokenizer)));
+            coro_t::pull_type tracer(boost::bind(trace, _1, boost::ref(filter)));
+            BOOST_FOREACH(std::string token,tracer){
+                // just iterate, we're already pulling through tracer
+            }
+        }
+
+        {
+            std::cout << "\nlayout() as coroutine::push_type:\n";
+            std::istringstream infile(data);
+            coro_t::pull_type reader(boost::bind(readlines, _1, boost::ref(infile)));
+            coro_t::pull_type tokenizer(boost::bind(tokenize, _1, boost::ref(reader)));
+            coro_t::pull_type filter(boost::bind(only_words, _1, boost::ref(tokenizer)));
+            coro_t::push_type writer(boost::bind(layout, _1, 5, 15));
+            BOOST_FOREACH(std::string token,filter){
+                writer(token);
+            }
+        }
+
+        {
+            std::cout << "\nfiltering output:\n";
+            std::istringstream infile(data);
+            coro_t::pull_type reader(boost::bind(readlines,_1,boost::ref(infile)));
+            coro_t::pull_type tokenizer(boost::bind(tokenize,_1,boost::ref(reader)));
+            coro_t::push_type writer(boost::bind(layout,_1,5,15));
+            // Because of the symmetry of the API, we can use any of these
+            // chaining functions in a push_type coroutine chain as well.
+            coro_t::push_type filter(boost::bind(only_words,boost::ref(writer),_1));
+            BOOST_FOREACH(std::string token,tokenizer){
+                filter(token);
+            }
+        }
+
+
+
 [heading asynchronous operations with boost.asio]
 
 In the past the code using asio's ['asynchronous operations] was scattered by callbacks.