Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/spirit/phoenix/doc/adaptable_closures.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 10.9 KB
Line 
1<html>
2<head>
3<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
4<title>Adaptable closures</title>
5<link rel="stylesheet" href="theme/style.css" type="text/css">
6<link rel="prev" href="binders.html">
7<link rel="next" href="lazy_construction.html">
8</head>
9<body>
10<table width="100%" height="48" border="0" background="theme/bkd2.gif" cellspacing="2">
11  <tr>
12    <td width="10">
13    </td>
14    <td width="85%">
15      <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Adaptable closures</b></font>
16    </td>
17    <td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" align="right" border="0"></a></td>
18  </tr>
19</table>
20<br>
21<table border="0">
22  <tr>
23    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
24    <td width="30"><a href="binders.html"><img src="theme/l_arr.gif" border="0"></a></td>
25    <td width="20"><a href="lazy_construction.html"><img src="theme/r_arr.gif" border="0"></a></td>
26   </tr>
27</table>
28<p>
29The framework will not be complete without some form of closures support. Closures encapsulate a stack frame where local variables are created upon entering a function and destructed upon exiting. Closures provide an environment for local variables to reside. Closures can hold heterogeneous types.</p>
30<p>
31Phoenix closures are true hardware stack based. Closures enable true reentrancy in lambda functions. A closure provides access to a function stack frame where local variables reside. Modeled after Pascal nested stack frames, closures can be nested just like nested functions where code in inner closures may access local variables from in-scope outer closures (accessing inner scopes from outer scopes is an error and will cause a run-time assertion failure).</p>
32<table width="80%" border="0" align="center">
33  <tr>
34    <td class="note_box">
35<img src="theme/lens.gif"></img> <b>Spirit Closures</b><br><br>
36<a href="http://spirit.sourceforge.net">
37Spirit</a> uses Phoenix closures to allow parameter passing (inherited and synthetic attributes, in parsing parlance) upstream and downstream in a parse traversal (see <a href="../../index.html">
38Spirit</a> documentation).    </td>
39  </tr>
40</table>
41<p>
42There are three (3) interacting classes:</p>
43<p>
44<b>1) closure:</b></p>
45<p>
46At the point of declaration, a closure does not yet create a stack frame nor instantiate any variables. A closure declaration declares the types and names of the local variables. The closure class is meant to be subclassed. It is the responsibility of a closure subclass to supply the names for each of the local variable in the closure. Example:</p>
47<code><pre>
48    <span class=keyword>struct </span><span class=identifier>my_closure </span><span class=special>: </span><span class=identifier>closure</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=identifier>string</span><span class=special>, </span><span class=keyword>double</span><span class=special>&gt; {
49
50        </span><span class=identifier>member1 </span><span class=identifier>num</span><span class=special>;        // </span><span class=identifier>names </span><span class=identifier>the </span><span class=number>1</span><span class=identifier>st </span><span class=special>(</span><span class=keyword>int</span><span class=special>) </span><span class=identifier>local </span><span class=identifier>variable
51        </span><span class=identifier>member2 </span><span class=identifier>message</span><span class=special>;    // </span><span class=identifier>names </span><span class=identifier>the </span><span class=number>2</span><span class=identifier>nd </span><span class=special>(</span><span class=identifier>string</span><span class=special>) </span><span class=identifier>local </span><span class=identifier>variable
52        </span><span class=identifier>member3 </span><span class=identifier>real</span><span class=special>;       // </span><span class=identifier>names </span><span class=identifier>the </span><span class=number>3</span><span class=identifier>rd </span><span class=special>(</span><span class=keyword>double</span><span class=special>) </span><span class=identifier>local </span><span class=identifier>variable
53    </span><span class=special>};
54
55    </span><span class=identifier>my_closure </span><span class=identifier>clos</span><span class=special>;
56</span></pre></code>
57<p>
58Now that we have a closure 'clos', its local variables can be accessed lazily using the dot notation. Each qualified local variable can be used just like any primitive actor (see primitives). Examples:</p>
59<code><pre>
60    <span class=identifier>clos</span><span class=special>.</span><span class=identifier>num </span><span class=special>= </span><span class=number>30
61    </span><span class=identifier>clos</span><span class=special>.</span><span class=identifier>message </span><span class=special>= </span><span class=identifier>arg1
62    </span><span class=identifier>clos</span><span class=special>.</span><span class=identifier>real </span><span class=special>= </span><span class=identifier>clos</span><span class=special>.</span><span class=identifier>num </span><span class=special>* </span><span class=number>1e6
63</span></pre></code>
64<p>
65The examples above are lazily evaluated. As usual, these expressions return composite actors that will be evaluated through a second function call invocation (see operators). Each of the members (clos.xxx) is an actor. As such, applying the operator() will reveal its identity:</p>
66<code><pre>
67    <span class=identifier>clos</span><span class=special>.</span><span class=identifier>num</span><span class=special>() // </span><span class=identifier>will </span><span class=keyword>return </span><span class=identifier>the </span><span class=identifier>current </span><span class=identifier>value </span><span class=identifier>of </span><span class=identifier>clos</span><span class=special>.</span><span class=identifier>num
68</span></pre></code>
69<table width="80%" border="0" align="center">
70  <tr>
71    <td class="note_box">
72<img src="theme/note.gif"></img> <b>Acknowledgement:</b><br><br><b>Juan Carlos Arevalo-Baeza</b> (JCAB) introduced and initilally implemented the closure member names that uses the dot notation and <b>Martin Wille</b> who improved multi thread safety using <a href="http://www.boost.org">
73Boost</a> Threads.    </td>
74  </tr>
75</table>
76<p>
77<b>2) closure_member</b></p>
78<p>
79The named local variables of closure 'clos' above are actually closure members. The closure_member class is an actor and conforms to its conceptual interface. member1..memberN are predefined typedefs that correspond to each of the listed types in the closure template parameters.</p>
80<p>
81<b>3) closure_frame</b></p>
82<p>
83When a closure member is finally evaluated, it should refer to an actual instance of the variable in the hardware stack. Without doing so, the process is not complete and the evaluated member will result to an assertion failure. Remember that the closure is just a declaration. The local variables that a closure refers to must still be instantiated.</p>
84<p>
85The closure_frame class does the actual instantiation of the local variables and links these variables with the closure and all its members. There can be multiple instances of closure_frames typically situated in the stack inside a function. Each closure_frame instance initiates a stack frame with a new set of closure local variables. Example:</p>
86<code><pre>
87    <span class=keyword>void </span><span class=identifier>foo</span><span class=special>()
88    {
89        </span><span class=identifier>closure_frame</span><span class=special>&lt;</span><span class=identifier>my_closure</span><span class=special>&gt; </span><span class=identifier>frame</span><span class=special>(</span><span class=identifier>clos</span><span class=special>);
90        /* </span><span class=keyword>do </span><span class=identifier>something </span><span class=special>*/
91    }
92</span></pre></code>
93<p>
94where 'clos' is an instance of our closure 'my_closure' above. Take note that the usage above precludes locally declared classes. If my_closure is a locally declared type, we can still use its self_type as a paramater to closure_frame:</p>
95<code><pre>
96    <span class=identifier>closure_frame</span><span class=special>&lt;</span><span class=identifier>my_closure</span><span class=special>::</span><span class=identifier>self_type</span><span class=special>&gt; </span><span class=identifier>frame</span><span class=special>(</span><span class=identifier>clos</span><span class=special>);
97</span></pre></code>
98<p>
99Upon instantiation, the closure_frame links the local variables to the closure. The previous link to another closure_frame instance created before is saved. Upon destruction, the closure_frame unlinks itself from the closure and relinks the preceding closure_frame prior to this instance.</p>
100<p>
101The local variables in the closure 'clos' above is default constructed in the stack inside function 'foo'. Once 'foo' is exited, all of these local variables are destructed. In some cases, default construction is not desirable and we need to initialize the local closure variables with some values. This can be done by passing in the initializers in a compatible tuple. A compatible tuple is one with the same number of elements as the destination and where each element from the destination can be constructed from each corresponding element in the source. Example:</p>
102<code><pre>
103    <span class=identifier>tuple</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>, </span><span class=keyword>char </span><span class=keyword>const</span><span class=special>*, </span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>init</span><span class=special>(</span><span class=number>123</span><span class=special>, </span><span class=string>&quot;Hello&quot;</span><span class=special>, </span><span class=number>1000</span><span class=special>);
104    </span><span class=identifier>closure_frame</span><span class=special>&lt;</span><span class=identifier>my_closure</span><span class=special>&gt; </span><span class=identifier>frame</span><span class=special>(</span><span class=identifier>clos</span><span class=special>, </span><span class=identifier>init</span><span class=special>);
105</span></pre></code>
106<p>
107Here now, our closure_frame's variables are initialized with int: 123, char const*: &quot;Hello&quot; and int: 1000.</p>
108<table border="0">
109  <tr>
110    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
111    <td width="30"><a href="binders.html"><img src="theme/l_arr.gif" border="0"></a></td>
112    <td width="20"><a href="lazy_construction.html"><img src="theme/r_arr.gif" border="0"></a></td>
113   </tr>
114</table>
115<br>
116<hr size="1">
117<p class="copyright">Copyright &copy; 2001-2002 Joel de Guzman<br>
118  <br>
119<font size="2">Use, modification and distribution is subject to the Boost Software
120    License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
121    http://www.boost.org/LICENSE_1_0.txt) </font> </p>
122</body>
123</html>
Note: See TracBrowser for help on using the repository browser.