Boost-Commit :

Date view	Thread view	Subject view	Author view

From: mconsoni_at_[hidden]
Date: 2007-06-26 18:26:26

Next message: mconsoni_at_[hidden]: "[Boost-commit] svn:boost r7183"
Previous message: mconsoni_at_[hidden]: "[Boost-commit] svn:boost r7181"

Author: mconsoni
Date: 2007-06-26 18:26:25 EDT (Tue, 26 Jun 2007)
New Revision: 7182
URL: http://svn.boost.org/trac/boost/changeset/7182

Log:

- this ones were generated as part of the new info class section and appendices.

Added:
   sandbox/libs/extension/doc/html/boost_extension/appendices/
   sandbox/libs/extension/doc/html/boost_extension/appendices/appendix_a.html
   sandbox/libs/extension/doc/html/boost_extension/info.html

Added: sandbox/libs/extension/doc/html/boost_extension/appendices/appendix_a.html
==============================================================================
--- (empty file)
+++ sandbox/libs/extension/doc/html/boost_extension/appendices/appendix_a.html 2007-06-26 18:26:25 EDT (Tue, 26 Jun 2007)
@@ -0,0 +1,75 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Appendix A - Windows Export and Import Declarations</title>
+<link rel="stylesheet" href="../../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
+<link rel="start" href="../../index.html" title="Chapter 1. Boost.Extension 1.0">
+<link rel="up" href="../appendices.html" title=" Appendices">
+<link rel="prev" href="../appendices.html" title=" Appendices">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../appendices.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../appendices.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_extension.appendices.appendix_a"></a> Appendix A - Windows Export and Import Declarations</h3></div></div></div>
+
+ On the Windows platform, special export declarations are required to make
+ functions or classes in a .dll file accessible to the outside world. For
+ normal usage of Boost.Extension, the only place this is required is in the
+ one function that is exported from each .dll. The Hello World sample program
+ illustrates how this is done using <code class="computeroutput">BOOST_EXTENSION_EXPORT</code>.
+ 
+
+ For implementation inheritance across shared libraries, such as that in the
+ Multiple Inheritance sample, each class that is not header-only that needs
+ to be exported must have these declarations included. To make it more difficult,
+ they must be different depending on whether the class is being imported into
+ or exported from the current module. The Multiple Inheritance sample shows
+ how this is done.
+ 
+<a name="boost_extension.appendices.appendix_a.warning"></a><h3>
+<a name="id2576093"></a>
+ Warning
+ </h3>
+
+ Now for a word of warning that many of you will ignore: In the great majority
+ of cases, even if non-header-only implementation inheritance across shared
+ libraries seems like a good idea, there is probably a better solution. Although
+ it certainly has its uses, it can cause problems like the following:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ Version problems - if the original implementation changes at all, every
+ dependent shared library must be recompiled with the new implementation.
+ </li>
+<li>
+ Tight coupling between shared libraries. One of the primary reasons for
+ using shared libraries is to decrease coupling, and promote reuse.
+ </li>
+<li>
+ It can lead to overly complicated, over-designed class hierarchies.
+ </li>
+</ul></div>
+</div>
+<table width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2007 Jeremy Pack, Mariano G. Consoni</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../appendices.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../appendices.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>

Added: sandbox/libs/extension/doc/html/boost_extension/info.html
==============================================================================
--- (empty file)
+++ sandbox/libs/extension/doc/html/boost_extension/info.html 2007-06-26 18:26:25 EDT (Tue, 26 Jun 2007)
@@ -0,0 +1,240 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title> Info Classes</title>
+<link rel="stylesheet" href="../boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
+<link rel="start" href="../index.html" title="Chapter 1. Boost.Extension 1.0">
+<link rel="up" href="../index.html" title="Chapter 1. Boost.Extension 1.0">
+<link rel="prev" href="shared_libraries.html" title=" Shared Libraries">
+<link rel="next" href="performance_analysis.html" title=" Performance Analysis">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%">
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="shared_libraries.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="performance_analysis.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="boost_extension.info"></a> Info Classes</h2></div></div></div>
+
+ In this section we explain how to use Info classes in Boost.Extensions.
+ 
+
+ Info classes is a mechanism that allows you to store important information
+ of each implementation. The type and utility of this information is arbitrary
+ as the Info class is a template argument of the factories where the user registers
+ its own implementations, and for that reason any kind of information could
+ be stored.
+ 
+
+ Let's see how can we use it with an example first and then we will be able
+ to summarize the concepts.
+ 
+
+ Surely you remember our very first example, that of course it's called HelloWorld.
+ Well, let's imagine that we now want a multi-language Hello World. Of course
+ there are better ways of designing it, but as we want to picture how the Info
+ class could be used we'll take this approach.
+ 
+
+ First, we define an implementation of the <code class="literal">word</code> interface
+ for each combination of word and language. Then we have for example the class
+ <code class="literal">monde</code> that implements the <code class="literal">word</code> interface
+ for the french language in this case.
+ 
+
+ Let's see the code:
+ 
+
+
+
+<pre class="programlisting">
+class world : public word
+{
+public:
+ virtual const char * get_val(){return "world!";}
+};
+
+class mundo : public word
+{
+public:
+ virtual const char * get_val(){return "mundo!";}
+};
+
+class monde : public word
+{
+public:
+ virtual const char * get_val(){return "monde!";}
+};
+
+class mondo : public word
+{
+public:
+ virtual const char * get_val(){return "mondo!";}
+};
+
+
+class hello : public word
+{
+public:
+ virtual const char * get_val(){return "hello";}
+};
+
+class hola : public word
+{
+public:
+ virtual const char * get_val(){return "hola";}
+};
+
+class bonjour : public word
+{
+public:
+ virtual const char * get_val(){return "bonjour";}
+};
+
+class buonasera : public word
+{
+public:
+ virtual const char * get_val(){return "buonasera";}
+};
+</pre>
+
+ 
+
+ Now we have the word 'hello' and 'world' implemented in several languages.
+ 
+
+ And then, how can we specify, given an implementation of <code class="literal">word</code>
+ interface, in which language is the translation and which is the original word
+ (in a reference language, english in this case)? Well, as we want to store
+ implementation specific information we could use the Info class for this implementations.
+ 
+
+ We define a new class called <code class="literal">word_description</code> where we can
+ define the language and the original word. This will be our Info class:
+ 
+
+
+
+<pre class="programlisting">
+struct word_description
+{
+ std::string language;
+ std::string english_translation;
+
+ word_description(std::string language, std::string english_translation)
+ : language(language), english_translation(english_translation) {}
+};
+</pre>
+
+ 
+
+ Finally, just store a <code class="literal">word_description</code> instance when adding
+ the words to the factory map, describing the original word and the language:
+ 
+
+
+
+<pre class="programlisting">
+extern "C" void BOOST_EXTENSION_EXPORT_DECL extension_export_multilanguage_word(boost::extensions::factory_map & fm)
+{
+ fm.add<hola, word, word_description>(word_description("spanish", "hello"));
+ fm.add<mundo, word, word_description>(word_description("spanish", "world!"));
+
+ fm.add<bonjour, word, word_description>(word_description("french", "hello"));
+ fm.add<monde, word, word_description>(word_description("french", "world!"));
+
+ fm.add<buonasera, word, word_description>(word_description("italian", "hello"));
+ fm.add<mondo, word, word_description>(word_description("italian", "world!"));
+
+ fm.add<hello, word, word_description>(word_description("english", "hello"));
+ fm.add<world, word, word_description>(word_description("english", "world!"));
+}
+</pre>
+
+ 
+
+ In the code we could see that add argument is a Info class instance. In this
+ case is <code class="literal">word_description</code> which receives the language and
+ word as arguments.
+ 
+
+ Now we could start using that information in the main code. Rerieving Info
+ class is easy, you should just call <code class="literal">get_info()</code> method of
+ the factory.
+ 
+
+ Let's see some code using the multilanguage hello world words:
+ 
+
+
+
+<pre class="programlisting">
+for (std::list<factory<word, word_description> >::iterator current_word = factory_list.begin();
+ current_word != factory_list.end(); ++current_word)
+{
+ std::auto_ptr<word> word_ptr(current_word->create());
+ std::cout << word_ptr->get_val() << " is " << current_word->get_info().english_translation
+ << " in " << current_word->get_info().language << std::endl;
+}
+std::cout << std::endl;
+</pre>
+
+ 
+
+ And we get the following output:
+ 
+<div class="informaltable">
+<h4>
+<a name="id2575920"></a>
+ </h4>
+<table class="table">
+<colgroup><col></colgroup>
+<tbody><tr><td><code class="literal">hola is hello in spanish mundo! is world! in spanish 
+ bonjour is hello in french monde! is world! in french buonasera
+ is hello in italian mondo! is world! in italian hello is
+ hello in english world! is world! in english </code></td></tr></tbody>
+</table>
+</div>
+
+ Now that we have described our example the major parts could be summarized:
+ 
+<div class="orderedlist"><ol type="1">
+<li>
+ We just define our interface and implementations normally.
+ </li>
+<li>
+ We define the Info class.
+ </li>
+<li>
+ When we add the implementations to the factory_map we construct a new Info
+ class instance for each implementation, storing the needed data.
+ </li>
+<li>
+ Finally, we could use the <code class="literal">get_info</code> method in the main
+ file to retrieve the data.
+ </li>
+</ol></div>
+
+ Tutorial 5 describes a more complex example of the use of the Info class.
+ 
+</div>
+<table width="100%"><tr>
+<td align="left"></td>
+<td align="right">Copyright © 2007 Jeremy Pack, Mariano G. Consoni</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="shared_libraries.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="performance_analysis.html"><img src="../images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Next message: mconsoni_at_[hidden]: "[Boost-commit] svn:boost r7183"
Previous message: mconsoni_at_[hidden]: "[Boost-commit] svn:boost r7181"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk