ceph/src/boost/libs/proto/doc/reference/context/callable.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3   Copyright 2012 Eric Niebler
   4
   5   Distributed under the Boost
   6   Software License, Version 1.0. (See accompanying
   7   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <header name="boost/proto/context/callable.hpp">
  10   <para>Definintion of <computeroutput><classname alt="boost::proto::context::callable_context">proto::context::callable_context&lt;&gt;</classname></computeroutput>,
  11     an evaluation context for <computeroutput><functionname alt="boost::proto::eval">proto::eval()</functionname></computeroutput>
  12     that fans out each node and calls the derived context type with the expressions constituents. If the derived context
  13     doesn't have an overload that handles this node, fall back to some other context. </para>
  14   <namespace name="boost">
  15     <namespace name="proto">
  16       <namespace name="context">
  17         <struct name="callable_eval">
  18           <template>
  19             <template-type-parameter name="Expr"/>
  20             <template-type-parameter name="Context"/>
  21           </template>
  22           <purpose>A BinaryFunction that accepts a Proto expression and a callable context and calls
  23             the context with the expression tag and children as arguments, effectively fanning the
  24             expression out. </purpose>
  25           <description>
  26             <para>
  27               <computeroutput>proto::context::callable_eval&lt;&gt;</computeroutput> requires that
  28               <computeroutput>Context</computeroutput> is a <conceptname>PolymorphicFunctionObject</conceptname>
  29               that can be invoked with <computeroutput>Expr</computeroutput>'s tag and children as
  30               expressions, as follows:
  31               <programlisting>context(typename Expr::proto_tag(), <functionname>proto::child_c</functionname>&lt;0&gt;(expr), ... <functionname>proto::child_c</functionname>&lt;N&gt;(expr))</programlisting>
  32             </para>
  33           </description>
  34           <typedef name="result_type">
  35             <type>typename boost::result_of&lt;
  36     Context(
  37       typename Expr::proto_tag,
  38       typename proto::result_of::child_c&lt;0&gt;::type,
  39       ...
  40       typename proto::result_of::child_c&lt;N&gt;::type,
  41     )&gt;::type
  42   </type>
  43           </typedef>
  44
  45           <method-group name="public member functions">
  46             <method name="operator()" cv="const">
  47               <type>result_type</type>
  48               <parameter name="expr">
  49                 <paramtype>Expr &amp;</paramtype>
  50                 <description>
  51                   <para>The current expression </para>
  52                 </description>
  53               </parameter>
  54               <parameter name="context">
  55                 <paramtype>Context &amp;</paramtype>
  56                 <description>
  57                   <para>The callable evaluation context </para>
  58                 </description>
  59               </parameter>
  60               <returns>
  61                 <para>
  62                   <computeroutput>
  63                     context(typename Expr::proto_tag(),
  64                     <functionname>proto::child_c</functionname>&lt;0&gt;(expr),...
  65                     <functionname>proto::child_c</functionname>&lt;N&gt;(expr))
  66                   </computeroutput>
  67                 </para>
  68               </returns>
  69             </method>
  70           </method-group>
  71         </struct>
  72
  73         <struct name="callable_context">
  74           <template>
  75             <template-type-parameter name="Context"/>
  76             <template-type-parameter name="DefaultCtx">
  77               <default><classname>proto::context::default_context</classname></default>
  78             </template-type-parameter>
  79           </template>
  80           <purpose>An evaluation context adaptor that makes authoring a context a simple matter of
  81             writing function overloads, rather then writing template specializations.</purpose>
  82           <description>
  83             <para>
  84               <computeroutput>proto::callable_context&lt;&gt;</computeroutput> is a base class that
  85               implements the context protocol by passing fanned-out expression nodes to the derived
  86               context, making it easy to customize the handling of expression types by writing function
  87               overloads. Only those expression types needing special handling require explicit handling.
  88               All others are dispatched to a user-specified default context,
  89               <computeroutput>DefaultCtx</computeroutput>.
  90             </para>
  91             <para>
  92               <computeroutput>proto::callable_context&lt;&gt;</computeroutput> is defined simply as:
  93             </para>
  94             <para>
  95               <programlisting>template&lt;typename Context, typename DefaultCtx = default_context&gt;
  96 struct callable_context {
  97   template&lt;typename Expr, typename ThisContext = Context&gt;
  98   struct eval :
  99     mpl::if_&lt;
 100       is_expr_handled_&lt;Expr, Context&gt;, // For exposition
 101       <classname>proto::context::callable_eval</classname>&lt;Expr, ThisContext&gt;,
 102       typename DefaultCtx::template eval&lt;Expr, Context&gt;
 103     &gt;::type
 104   {};
 105 };</programlisting>
 106             </para>
 107             <para>
 108               The Boolean metafunction <computeroutput>is_expr_handled_&lt;&gt;</computeroutput> uses
 109               metaprogramming tricks to determine whether <computeroutput>Context</computeroutput> has
 110               an overloaded function call operator that accepts the fanned-out constituents of an
 111               expression of type <computeroutput>Expr</computeroutput>. If so, the handling of the
 112               expression is dispatched to
 113               <computeroutput><classname>proto::context::callable_eval&lt;&gt;</classname></computeroutput>.
 114               If not, it is dispatched to the user-specified <computeroutput>DefaultCtx</computeroutput>.
 115             </para>
 116             <para>
 117               <emphasis role="bold">Example:</emphasis>
 118             </para>
 119             <para>
 120               <programlisting>// An evaluation context that increments all
 121 // integer terminals in-place.
 122 struct increment_ints :
 123   <classname>proto::context::callable_context</classname>&lt;
 124     increment_ints const                // derived context
 125     <classname>proto::context::null_context</classname> const  // fall-back context
 126   &gt;
 127 {
 128     typedef void result_type;
 129
 130     // Handle int terminals here:
 131     void operator()(proto::tag::terminal, int &amp;i) const
 132     {
 133        ++i;
 134     }
 135 };</programlisting>
 136             </para>
 137             <para>
 138               With <computeroutput>increment_ints</computeroutput>, we can do the following:
 139             </para>
 140             <para>
 141               <programlisting><classname>proto::literal</classname>&lt;int&gt; i = 0, j = 10;
 142 proto::eval( i - j * 3.14, increment_ints() );
 143
 144 assert( i.get() == 1 &amp;&amp; j.get() == 11 );</programlisting>
 145             </para>
 146           </description>
 147           <struct name="eval">
 148             <template>
 149               <template-type-parameter name="Expr"/>
 150               <template-type-parameter name="ThisContext">
 151                 <default>Context</default>
 152               </template-type-parameter>
 153             </template>
 154             <description>
 155               <para>
 156                 A BinaryFunction that accepts an <computeroutput>Expr</computeroutput> and a
 157                 <computeroutput>Context</computeroutput>, and either fans out the expression and passes
 158                 it to the context, or else hands off the expression to <computeroutput>DefaultCtx</computeroutput>.
 159               </para>
 160               <para>
 161                 If <computeroutput>Context</computeroutput> is a <conceptname>PolymorphicFunctionObject</conceptname>
 162                 such that it can be invoked with the tag and children of <computeroutput>Expr</computeroutput>, as
 163                 <computeroutput>ctx(typename Expr::proto_tag(), child_c&lt;0&gt;(expr),... child_c&lt;N&gt;(expr))</computeroutput>,
 164                 then <computeroutput>eval&lt;Expr, ThisContext&gt;</computeroutput> inherits from
 165                 <computeroutput><classname>proto::context::callable_eval</classname>&lt;Expr, ThisContext&gt;</computeroutput>.
 166                 Otherwise, <computeroutput>eval&lt;Expr, ThisContext&gt;</computeroutput> inherits from
 167                 <computeroutput>DefaultCtx::eval&lt;Expr, Context&gt;</computeroutput>.
 168               </para>
 169             </description>
 170             <inherit><type><replaceable>see-below</replaceable></type></inherit>
 171           </struct>
 172         </struct>
 173       </namespace>
 174     </namespace>
 175   </namespace>
 176 </header>