Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Annotation of /sml/trunk/src/cml/doc/HTML/sync-var.html
ViewVC logotype

Annotation of /sml/trunk/src/cml/doc/HTML/sync-var.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2 - (view) (download) (as text)

1 : monnier 2 <!-- sync-var.html -->
2 :    
3 :     <!-- COPYRIGHT (c) 1995 AT\|@AMP\|T Bell Laboratories. -->
4 :    
5 :     <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.2//EN">
6 :     <HTML>
7 :     <HEAD>
8 :     <TITLE>The SyncVar structure</TITLE>
9 :     </HEAD>
10 :     <BODY>
11 :     <H1><A NAME="top-of-document">The Concurrent ML Reference Manual</A></H1>
12 :     <HR>
13 :    
14 :     <H3>The <CODE>SyncVar</CODE> structure</H3>
15 :     <P>
16 :     The SyncVar structure provides <B>Id</B>-style synchronous variables (or memory cells). These variables have two states: <I>empty</I> and <I>full</I>. An attempt to read a value from an empty variable blocks the calling thread until there is a value available. An attempt to put a value into a variable that is full results in the <A HREF="sync-var.html#SIG:SYNC_VAR.Put:EXN:SPEC">Put</A> exception being raised. There are two kinds of synchronous variables: I-variables are write-once, while M-variables are mutable.
17 :     <HR>
18 :     <H4>Synopsis</H4>
19 :     <BLOCKQUOTE>
20 :     <CODE><B>signature </B><A NAME="SYNC_VAR:SIG:SPEC"><CODE>SYNC_VAR</CODE></A><BR>
21 :     <B>structure </B><A NAME="SyncVar:STR:SPEC"><CODE>SyncVar</CODE></A><B> : </B>SYNC_VAR<BR>
22 :     </CODE>
23 :     </BLOCKQUOTE>
24 :     <HR>
25 :     <H4>Interface</H4>
26 :     <BLOCKQUOTE>
27 :     <CODE><B>exception</B> <A NAME="SIG:SYNC_VAR.Put:EXN:SPEC" HREF="#SIG:SYNC_VAR.Put:EXN">Put</A><BR>
28 :     <B>type</B> 'a <A NAME="SIG:SYNC_VAR.ivar:TY:SPEC" HREF="#SIG:SYNC_VAR.ivar:TY">ivar</A><BR>
29 :     <B>val</B> <A NAME="SIG:SYNC_VAR.iVar:VAL:SPEC" HREF="#SIG:SYNC_VAR.iVar:VAL">iVar</A> <B>:</B> unit -&gt; 'a ivar <BR>
30 :     <B>val</B> <A NAME="SIG:SYNC_VAR.iPut:VAL:SPEC" HREF="#SIG:SYNC_VAR.iPut:VAL">iPut</A> <B>:</B> ('a ivar * 'a) -&gt; unit <BR>
31 :     <B>val</B> <A NAME="SIG:SYNC_VAR.iGet:VAL:SPEC" HREF="#SIG:SYNC_VAR.iGet:VAL">iGet</A> <B>:</B> 'a ivar -&gt; 'a <BR>
32 :     <B>val</B> <A NAME="SIG:SYNC_VAR.iGetEvt:VAL:SPEC" HREF="#SIG:SYNC_VAR.iGetEvt:VAL">iGetEvt</A> <B>:</B> 'a ivar -&gt; 'a event <BR>
33 :     <B>val</B> <A NAME="SIG:SYNC_VAR.iGetPoll:VAL:SPEC" HREF="#SIG:SYNC_VAR.iGetPoll:VAL">iGetPoll</A> <B>:</B> 'a ivar -&gt; 'a option <BR>
34 :     <B>val</B> <A NAME="SIG:SYNC_VAR.sameIVar:VAL:SPEC" HREF="#SIG:SYNC_VAR.sameIVar:VAL">sameIVar</A> <B>:</B> ('a ivar * 'a ivar) -&gt; bool <BR>
35 :     <B>type</B> 'a <A NAME="SIG:SYNC_VAR.mvar:TY:SPEC" HREF="#SIG:SYNC_VAR.mvar:TY">mvar</A><BR>
36 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mVar:VAL:SPEC" HREF="#SIG:SYNC_VAR.mVar:VAL">mVar</A> <B>:</B> unit -&gt; 'a mvar <BR>
37 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mVarInit:VAL:SPEC" HREF="#SIG:SYNC_VAR.mVarInit:VAL">mVarInit</A> <B>:</B> 'a -&gt; 'a mvar <BR>
38 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mPut:VAL:SPEC" HREF="#SIG:SYNC_VAR.mPut:VAL">mPut</A> <B>:</B> ('a mvar * 'a) -&gt; unit <BR>
39 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mTake:VAL:SPEC" HREF="#SIG:SYNC_VAR.mTake:VAL">mTake</A> <B>:</B> 'a mvar -&gt; 'a <BR>
40 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mTakeEvt:VAL:SPEC" HREF="#SIG:SYNC_VAR.mTakeEvt:VAL">mTakeEvt</A> <B>:</B> 'a mvar -&gt; 'a event <BR>
41 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mGet:VAL:SPEC" HREF="#SIG:SYNC_VAR.mGet:VAL">mGet</A> <B>:</B> 'a mvar -&gt; 'a <BR>
42 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mGetEvt:VAL:SPEC" HREF="#SIG:SYNC_VAR.mGetEvt:VAL">mGetEvt</A> <B>:</B> 'a mvar -&gt; 'a event <BR>
43 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mTakePoll:VAL:SPEC" HREF="#SIG:SYNC_VAR.mTakePoll:VAL">mTakePoll</A> <B>:</B> 'a mvar -&gt; 'a option <BR>
44 :     <B>val</B> <A NAME="SIG:SYNC_VAR.mGetPoll:VAL:SPEC" HREF="#SIG:SYNC_VAR.mTakePoll:VAL">mGetPoll</A> <B>:</B> 'a mvar -&gt; 'a option <BR>
45 :     <B>val</B> <A NAME="SIG:SYNC_VAR.sameMVar:VAL:SPEC" HREF="#SIG:SYNC_VAR.sameMVar:VAL">sameMVar</A> <B>:</B> ('a mvar * 'a mvar) -&gt; bool <BR>
46 :     </CODE>
47 :     </BLOCKQUOTE>
48 :     <H4>Description</H4>
49 :     <DL>
50 :     <DT> <A NAME="SIG:SYNC_VAR.Put:EXN"><CODE><B>exception</B> Put</CODE></A>
51 :     <DD>
52 :     This exception is raised when an attempt is made to put a value into a value that is already full (see <A HREF="sync-var.html#SIG:SYNC_VAR.iPut:VAL:SPEC">iPut</A> and <A HREF="sync-var.html#SIG:SYNC_VAR.mPut:VAL:SPEC">mPut</A>).
53 :     <BR>
54 :     <BR>
55 :    
56 :     <DT> <A NAME="SIG:SYNC_VAR.ivar:TY"><CODE><B>type</B> 'a ivar</CODE></A>
57 :     <DD>
58 :     This is the type constructor for I-structured variables. I-structured variables are write-once variables that provide synchronization on read operations. They are especially useful for one-shot communications, such as reply messages in client/server protocols.
59 :     <BR>
60 :     <BR>
61 :    
62 :     <DT> <A NAME="SIG:SYNC_VAR.iVar:VAL"><CODE>iVar ()
63 :     </CODE></A>
64 :     <DD>
65 :     creates a new empty I-variable.
66 :     <BR>
67 :     <BR>
68 :    
69 :     <DT> <A NAME="SIG:SYNC_VAR.iPut:VAL"><CODE>iPut (<VAR>iv</VAR>, <VAR>x</VAR>)
70 :     </CODE></A>
71 :     <DD>
72 :     fills the I-variable <VAR>iv</VAR> with the value <VAR>x</VAR>. Any threads that are blocked on <VAR>iv</VAR> will be resumed. If <VAR>iv</VAR> already has a value in it, then the <A HREF="sync-var.html#SIG:SYNC_VAR.Put:EXN:SPEC">Put</A> exception is raised.
73 :     <BR>
74 :     <BR>
75 :    
76 :     <DT> <A NAME="SIG:SYNC_VAR.iGet:VAL"><CODE>iGet <VAR>iv</VAR>
77 :     </CODE></A>
78 :     <DD>
79 :     returns the contents of the I-variable <VAR>iv</VAR>. If the variable is empty, then the calling thread blocks until the variable becomes full.
80 :     <BR>
81 :     <BR>
82 :    
83 :     <DT> <A NAME="SIG:SYNC_VAR.iGetEvt:VAL"><CODE>iGetEvt <VAR>iv</VAR>
84 :     </CODE></A>
85 :     <DD>
86 :     returns an event-value that represents the <A HREF="sync-var.html#SIG:SYNC_VAR.iGet:VAL:SPEC">iGet</A> operation on <VAR>iv</VAR>.
87 :     <BR>
88 :     <BR>
89 :    
90 :     <DT> <A NAME="SIG:SYNC_VAR.iGetPoll:VAL"><CODE><B>val</B> iGetPoll</CODE></A>
91 :     <DD>
92 :     This is a non-blocking version of <A HREF="sync-var.html#SIG:SYNC_VAR.iGet:VAL:SPEC">iGet</A>. If the corresponding blocking form would block, then it returns NONE; otherwise it returns SOME of the variable's contents.
93 :     <BR>
94 :     <BR>
95 :    
96 :     <DT> <A NAME="SIG:SYNC_VAR.sameIVar:VAL"><CODE>sameIVar (<VAR>iv1</VAR>, <VAR>iv2</VAR>)
97 :     </CODE></A>
98 :     <DD>
99 :     returns <CODE>true</CODE>, if the <VAR>iv1</VAR> and <VAR>iv2</VAR> are the same I-variable.
100 :     <BR>
101 :     <BR>
102 :    
103 :     <DT> <A NAME="SIG:SYNC_VAR.mvar:TY"><CODE><B>type</B> 'a mvar</CODE></A>
104 :     <DD>
105 :     This is the type constructor for M-structured variables. Unlike <A HREF="sync-var.html#SIG:SYNC_VAR.ivar:TY:SPEC">ivar</A> values, M-structured variables may be updated multiple times. Like I-variables, however, they may only be written if they are empty.
106 :     <BR>
107 :     <BR>
108 :    
109 :     <DT> <A NAME="SIG:SYNC_VAR.mVar:VAL"><CODE>mVar ()
110 :     </CODE></A>
111 :     <DD>
112 :     creates a new empty M-variable.
113 :     <BR>
114 :     <BR>
115 :    
116 :     <DT> <A NAME="SIG:SYNC_VAR.mVarInit:VAL"><CODE>mVar x
117 :     </CODE></A>
118 :     <DD>
119 :     creates a new M-variable initialized to <VAR>x</VAR>.
120 :     <BR>
121 :     <BR>
122 :    
123 :     <DT> <A NAME="SIG:SYNC_VAR.mPut:VAL"><CODE>mPut (<VAR>mv</VAR>, <VAR>x</VAR>)
124 :     </CODE></A>
125 :     <DD>
126 :     fills the M-variable <VAR>mv</VAR> with the value <VAR>x</VAR>. Any threads that are blocked on <VAR>mv</VAR> will be resumed. If <VAR>mv</VAR> already has a value in it, then the <A HREF="sync-var.html#SIG:SYNC_VAR.Put:EXN:SPEC">Put</A> exception is raised.
127 :     <BR>
128 :     <BR>
129 :    
130 :     <DT> <A NAME="SIG:SYNC_VAR.mTake:VAL"><CODE>mTake <VAR>mv</VAR>
131 :     </CODE></A>
132 :     <DD>
133 :     removes and returns the contents of the M-variable <VAR>mv</VAR> making it empty. If the variable is already empty, then the calling thread is blocked until a value is available.
134 :     <BR>
135 :     <BR>
136 :    
137 :     <DT> <A NAME="SIG:SYNC_VAR.mTakeEvt:VAL"><CODE>mTakeEvt <VAR>mv</VAR>
138 :     </CODE></A>
139 :     <DD>
140 :     returns an event-value that represents the <A HREF="sync-var.html#SIG:SYNC_VAR.mTake:VAL:SPEC">mTake</A> operation on <VAR>mv</VAR>.
141 :     <BR>
142 :     <BR>
143 :    
144 :     <DT> <A NAME="SIG:SYNC_VAR.mGet:VAL"><CODE>mGet <VAR>mv</VAR>
145 :     </CODE></A>
146 :     <DD>
147 :     returns the contents of the M-variable <VAR>mv</VAR> without emptying the variable; if the variable is empty, then the thread blocks until a value is available. It is equivalent to the code:
148 :     <PRE>
149 :     let val x = <A HREF="sync-var.html#SIG:SYNC_VAR.mTake:VAL:SPEC">mTake</A> <VAR>mv</VAR> in <A HREF="sync-var.html#SIG:SYNC_VAR.mPut:VAL:SPEC">mPut</A>(<VAR>mv</VAR>, x); x end
150 :    
151 :     </PRE>
152 :    
153 :     <BR>
154 :     <BR>
155 :    
156 :     <DT> <A NAME="SIG:SYNC_VAR.mGetEvt:VAL"><CODE>mGetEvt <VAR>mv</VAR>
157 :     </CODE></A>
158 :     <DD>
159 :     returns an event-value that represents the <A HREF="sync-var.html#SIG:SYNC_VAR.mGet:VAL:SPEC">mGet</A> operation on <VAR>mv</VAR>.
160 :     <BR>
161 :     <BR>
162 :    
163 :     <DT> <A NAME="SIG:SYNC_VAR.mTakePoll:VAL"><CODE><B>val</B> mTakePoll</CODE></A>
164 :     <DT> <CODE><B>val</B> mGetPoll</CODE>
165 :     <DD>
166 :     These are non-blocking versions of <A HREF="sync-var.html#SIG:SYNC_VAR.mTake:VAL:SPEC">mTake</A> and <A HREF="sync-var.html#SIG:SYNC_VAR.mGet:VAL:SPEC">mGet</A> (respectively). If the corresponding blocking form would block, then they return NONE; otherwise they return SOME of the variable's contents.
167 :     <BR>
168 :     <BR>
169 :    
170 :     <DT> <A NAME="SIG:SYNC_VAR.sameMVar:VAL"><CODE>sameMVar (<VAR>mv1</VAR>, <VAR>mv2</VAR>)
171 :     </CODE></A>
172 :     <DD>
173 :     returns <CODE>true</CODE>, if <VAR>mv1</VAR> and <VAR>mv2</VAR> are the same M-variable.
174 :     <BR>
175 :     <BR>
176 :    
177 :     </DL>
178 :     <HR>
179 :     <H4>Discussion</H4>
180 :     <P>
181 :     I-variables provide a useful mechanism for implementing the reply communication in request/reply protocols. They may also be used to implement incremental data structures and streams.
182 :     <P>
183 :     A disciplined use of M-variables can provide an atomic read-modify-write operation.
184 :     <H4>See Also</H4>
185 :     <BLOCKQUOTE>
186 :     <A HREF="cml.html#CML:STR:SPEC">CML</A>
187 :     </BLOCKQUOTE>
188 :     <HR>
189 :     <B>[ <A HREF="index-all.html">INDEX</A> | <A HREF="sync-var.html">TOP</A>
190 :     | <A HREF="core-cml.html">Parent</A> | <A HREF="refman.html">Root</A>
191 :     ]</B>
192 :     <P>
193 :     <I>Last Modified November 16, 1995</I><BR>
194 :     Copyright &copy; 1996 AT&amp;T <BR>
195 :     <HR>
196 :     </BODY>
197 :     </HTML>

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0