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 -> 'a saref 21 22 exception Locked 23 val saset: 'a saref * 'a -> unit 24 val savalue: 'a saref -> '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 -> '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 -> 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 -> '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>