ceph/src/boost/libs/signals/doc/reference/visit_each.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
   3   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
   4 <header name="boost/visit_each.hpp" last-revision="$Date$">
   5   <namespace name="boost">
   6     <function name="visit_each">
   7       <template>
   8         <template-type-parameter name="Visitor"/>
   9         <template-type-parameter name="T"/>
  10       </template>
  11       <type>void</type>
  12       <parameter name="visitor">
  13         <paramtype>const Visitor&amp;</paramtype>
  14       </parameter>
  15       <parameter name="t">
  16         <paramtype>const T&amp;</paramtype>
  17       </parameter>
  18       <parameter>
  19         <paramtype>int</paramtype>
  20       </parameter>
  21
  22       <purpose>Allow limited exploration of class members.</purpose>
  23
  24       <description>
  25         <para>The <functionname>visit_each</functionname> mechanism
  26         allows a visitor to be applied to every subobject in a given
  27         object. It is used by the Signals library to discover
  28         <classname>signals::trackable</classname> objects within a
  29         function object, but other uses may surface if used
  30         universally (e.g., conservative garbage collection). To fit
  31         within the <functionname>visit_each</functionname> framework,
  32         a <functionname>visit_each</functionname> overload must be
  33         supplied for each object type. </para>
  34       </description>
  35
  36       <effects><para><code>visitor(t)</code>, and for
  37       every subobject <code>x</code> of
  38       <code>t</code>:
  39         <itemizedlist>
  40           <listitem><para>If <code>x</code> is a reference, <code>visit_each(visitor, <functionname>ref</functionname>(x), 0)</code></para></listitem>
  41           <listitem><para>Otherwise, <code>visit_each(visitor, x, 0)</code></para></listitem>
  42         </itemizedlist>
  43       </para></effects>
  44
  45       <notes><para>The third parameter is
  46       <code>long</code> for the fallback version
  47       of <functionname>visit_each</functionname> and the argument
  48       supplied to this third paramter must always be 0. The third
  49       parameter is an artifact of the widespread lack of proper
  50       function template ordering, and will be removed in the future.</para>
  51
  52       <para>Library authors will be expected to add additional
  53       overloads that specialize the T argument for their classes, so
  54       that subobjects can be visited.</para>
  55
  56       <para>Calls to visit_each are required to be unqualified, to
  57       enable argument-dependent lookup.</para></notes>
  58     </function>
  59   </namespace>
  60 </header>