1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML>
3<HEAD>
4	<TITLE>The SingleAssignment structure</TITLE>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<link href="docstyle.css" rel="stylesheet" type="text/css">
7</HEAD>
8<BODY BGCOLOR="#ffffff">
9<ul class="nav">
10	<li><a href="Signal.html">Previous</a></li>
11	<li><a href="Basis.html">Up</a></li>
12	<li><a href="Threads.html">Next</a></li>
13</ul>
14<H2><STRONG><font face="Arial, Helvetica, sans-serif">SingleAssignment structure</font></STRONG></H2>
15<p>The <span class="identifier">SingleAssignment</span> structure provides a reference 
16  that can be assigned a value only once.</p>
17<pre class="mainsig">structure SingleAssignment:
18  sig
19    type 'a saref
20    val saref: unit -&gt; 'a saref
21
22    exception Locked
23    val saset: 'a saref * 'a -&gt; unit
24    val savalue: 'a saref -&gt; 'a option
25  end</pre>
26<div class="entryblock"> 
27  <pre class="entrycode"><a name="saref_type" id="saref_type"></a>type 'a saref</pre>
28  <div class="entrytext">
29    <p>The type of a single-assignment reference. It is similar to the standard 
30      <span class="identifier">ref</span> type constructor.</p>
31  </div>
32</div>
33<div class="entryblock"> 
34  <pre class="entrycode"><a name="saref"></a>val saref: unit -&gt; 'a saref</pre>
35  <div class="entrytext">
36    <p>Construct a single-assignment reference.</p>
37  </div>
38</div>
39<div class="entryblock"> 
40  <pre class="entrycode"><a name="Locked"></a>exception Locked</pre>
41  <div class="entrytext">
42    <p>This exception is raised if an attempt is made to assign a value twice 
43      to the same reference.</p>
44  </div>
45</div>
46<div class="entryblock"> 
47  <pre class="entrycode"><a name="saset" id="saset"></a>val saset: 'a saref * 'a -&gt; unit</pre>
48  <div class="entrytext">
49    <p>Assign a value to the reference. If it has already been assigned a value 
50      this will raise Locked. Note that this function is not thread-safe. A <a href="Threads.html#mutex_type"><span class="identifier">mutex</span></a> 
51      must be associated with reference if there is the possibility that two different 
52      threads may attempt to assign to the same reference.</p>
53  </div>
54</div>
55<div class="entryblock"> 
56  <pre class="entrycode"><a name="savalue" id="savalue"></a>val savalue: 'a saref -&gt; 'a option</pre>
57  <div class="entrytext">
58    <p>Extract the current value of the reference. If it has not yet been assigned 
59      a value it will return <span class="identifier">NONE</span>. If it has, 
60      it will return <span class="identifier">SOME v</span> where <span class="identifier">v</span> 
61      is the value that was assigned.</p>
62  </div>
63</div>
64<p>The reason behind the <span class="identifier">SingleAssignment</span> structure 
65  has to do with the way the Poly/ML storage management system deals with <em>mutable</em> 
66  and <em>immutable</em> data. Immutable memory cells are given a value when they 
67  are created and once created never change. They are used for lists, tuples, 
68  vectors and other datatypes. In contrast, refs and arrays are mutable data. 
69  They are given a value when they are created in the same way as immutable data 
70  but their contents can change by assignment. In addition Standard ML also distinguishes 
71  between mutable and immutable data in the treatment of equality. Immutable data 
72  structures are considered equal if their contents are the same, mutable cells 
73  are considered equal only if they are the pointers to the same cell.</p>
74<p>Because of these differences mutable data has to be handled separately from 
75  immutable data by the garbage collector. Using mutable cells imposes an extra 
76  cost on each collection when compared with immutable data. In addition it is 
77  possible to reduce the heap size by merging immutable cells that have the same 
78  contents. In some circumstances the garbage collector may do this automatically; 
79  more often it is done explicitly using <a href="PolyMLStructure.html#shareCommonData"><span class="identifier">PolyML.shareCommonData</span></a>. 
80</p>
81<p>The <span class="identifier">SingleAssignment</span> structure allows for a 
82  combination of mutable and immutable data. A value of type <span class="identifier">saref</span> 
83  is initially mutable but once it has been assigned a value it is marked as immutable. 
84  This allows the garbage-collector and sharing code to treat it as purely immutable 
85  once it has been locked.</p>
86<p>A typical use for a single-assignment reference is when a data structure is 
87  being built by multiple threads. A <span class="identifier">saref</span> can 
88  be used within the data structure to represent a portion of the structure to 
89  be built and a thread created to build it. When the thread completes it assigns 
90  the <span class="identifier">saref</span> with the results of its work. The 
91  full structure is now immutable with all the advantages of immutable data.</p>
92<ul class="nav">
93	<li><a href="Signal.html">Previous</a></li>
94	<li><a href="Basis.html">Up</a></li>
95	<li><a href="Threads.html">Next</a></li>
96</ul>
97</BODY>
98</HTML>