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/ML-Doc/cml.mldoc
ViewVC logotype

Annotation of /sml/trunk/src/cml/doc/ML-Doc/cml.mldoc

Parent Directory Parent Directory | Revision Log Revision Log


Revision 107 - (view) (download)

1 : monnier 7 <!-- ../doc/mldoc/cml.mldoc -->
2 :    
3 :     <!DOCTYPE ML-DOC SYSTEM>
4 :    
5 : monnier 106 <COPYRIGHT OWNER="Bell Labs, Lucent Technologies" YEAR=1998>
6 : monnier 7 <COPYRIGHT OWNER="AT&AMP;T Bell Laboratories" YEAR=1995>
7 :     <COPYRIGHT OWNER="John H. Reppy" YEAR=1991>
8 :     <VERSION VERID="1.0" YEAR=1995 MONTH=11 DAY=16>
9 :     <TITLE>The CML structure</TITLE>
10 :    
11 : monnier 106 <INTERFACE>
12 : monnier 7 <HEAD>The <CD/CML/ structure</HEAD>
13 : monnier 106 <SEEALSO>
14 :     <STRREF DOCUMENT=SML-BASIS-DOC TOPID/Option/
15 :     <STRREF DOCUMENT=SML-BASIS-DOC TOPID/Time/
16 :     </SEEALSO>
17 : monnier 7
18 :     <PP>
19 :     <!-- Some general introductory text -->
20 :    
21 :     <STRUCTURE STRID="CML">
22 :     <SIGBODY SIGID="CML" FILE=CML-SIG>
23 :     <SPEC>
24 :     <TYPE><ID>thread_id
25 :     <COMMENT>
26 : monnier 106 <PP>
27 : monnier 7 Thread IDs are the unique IDs associated with &CML; threads.
28 :     These IDs are in an unspecified total order that can be used to
29 :     break cyclic depedencies (see <VALREF/compareTid/).
30 :     <SPEC>
31 :     <TYPE><TYPARAM>'a<ID>chan
32 :     <COMMENT>
33 : monnier 106 <PP>
34 : monnier 7 This is the type constructor for synchronous channels.
35 :     <SPEC>
36 :     <TYPE><TYPARAM>'a<ID>event
37 :     <COMMENT>
38 : monnier 106 <PP>
39 : monnier 7 Event values are abstract representations of synchronous operations
40 :     (so called <EM>first-class sychronous operations</EM>).
41 :     <SPEC>
42 :     <VAL>version<TY>{system : string, version_id : int list, date : string}
43 :     <VAL>banner<TY>string
44 :     <COMMENT>
45 : monnier 106 <PP>
46 : monnier 7 These specify the version of &CML; in the same format as &SMLNJ;.
47 :     <SPEC>
48 :     <VAL>spawnc<TY>('a -> unit) -> 'a -> thread_id
49 :     <VAL>spawn<TY>(unit -> unit) -> thread_id
50 :     <COMMENT>
51 :     <PROTOTY>
52 :     spawnc <ARG/f/ <ARG/x/
53 :     <PROTO>
54 :     spawn <ARG/f/
55 :     </PROTOTY>
56 :     creates a new thread of control to evaluate the body of <ARG/f/.
57 :     A new unique ID for the thread is created and returned.
58 :     <SPEC>
59 :     <VAL>yield<TY>unit -> unit
60 :     <COMMENT>
61 : monnier 106 <PP>
62 : monnier 7 This function can be used to implement an explicit context switch.
63 :     Since CML is preemptively scheduled, it should never be necessary for
64 :     user programs to call this function.
65 :     It is mainly used for performance measurements.
66 :     <SPEC>
67 :     <VAL>exit<TY>unit -> 'a
68 :     <COMMENT>
69 :     <PROTOTY>
70 :     exit ()
71 :     </PROTOTY>
72 :     causes the calling thread to terminate.
73 :     <!-- say something about <VALREF/joinEvt/ -->
74 :     <SPEC>
75 :     <VAL>getTid<TY>unit -> thread_id
76 :     <COMMENT>
77 :     <PROTOTY>
78 :     getTid ()
79 :     </PROTOTY>
80 :     returns the thread ID of the calling thread.
81 :     <SPEC>
82 :     <VAL>sameTid<TY>(thread_id * thread_id) -> bool
83 :     <COMMENT>
84 :     <PROTOTY>
85 :     sameTid (<ARG/tid1/, <ARG/tid2/)
86 :     </PROTOTY>
87 :     returns true, if the two thread IDs are the same ID.
88 :     <SPEC>
89 :     <VAL>compareTid<TY>(thread_id * thread_id) -> order
90 :     <COMMENT>
91 :     <PROTOTY>
92 :     compareTid (<ARG/tid1/, <ARG/tid2/)
93 :     </PROTOTY>
94 :     compares the two thread IDs and returns their order in the total
95 :     ordering of thread IDs.
96 :     The precise semantics of this ordering is left unspecified, other
97 :     than to say it is a total order.
98 :     <SPEC>
99 :     <VAL>hashTid<TY>thread_id -> word
100 :     <COMMENT>
101 :     <PROTOTY>
102 :     hashTid <ARG/tid/
103 :     </PROTOTY>
104 :     returns a hashing of the thread ID <ARG/tid/.
105 :     <SPEC>
106 :     <VAL>tidToString<TY>thread_id -> string
107 :     <COMMENT>
108 :     <PROTOTY>
109 :     tidToString <ARG/tid/
110 :     </PROTOTY>
111 :     returns a string representation of the thread ID <ARG/tid/.
112 :     <SPEC>
113 :     <VAL>joinEvt<TY>thread_id -> unit event
114 :     <COMMENT>
115 :     <PROTOTY>
116 :     joinEvt <ARG/tid/
117 :     </PROTOTY>
118 :     creates an event value for synchronizing on the termination of
119 :     the thread with the ID <ARG/tid/.
120 :     There are three ways that a thread may terminate: the function that
121 :     was passed to <VALREF/spawn/ may return; it may call the <VALREF/exit/
122 :     function, or it may have an uncaught exception.
123 :     Note that <VALREF NOLINK/joinEvt/ does not distinguish between these
124 :     cases; it also does not become enabled if the named thread deadlocks
125 :     (even if it is garbage collected).
126 :     <SPEC>
127 :     <VAL>channel<TY>unit -> 'a chan
128 :     <COMMENT>
129 :     <PROTOTY>
130 :     channel ()
131 :     </PROTOTY>
132 :     creates a new synchronous channel.
133 :     <SPEC>
134 :     <VAL>sameChannel<TY>('a chan * 'a chan) -> bool
135 :     <COMMENT>
136 :     <PROTOTY>
137 :     sameChannel (<ARG/ch1/, <ARG/ch2/)
138 :     </PROTOTY>
139 :     returns true, if the two channels are the same channel.
140 :     <SPEC>
141 :     <VAL>send<TY>('a chan * 'a) -> unit
142 :     <COMMENT>
143 :     <PROTOTY>
144 :     send (<ARG/ch/, <ARG/a/)
145 :     </PROTOTY>
146 :     sends the message <ARG/a/ on the synchronous channel <ARG/ch/.
147 :     This operation blocks the calling thread until there is another
148 :     thread attempting a <VALREF/recv/ operation on the channel <ARG/ch/.
149 :     <SPEC>
150 :     <VAL>recv<TY>'a chan -> 'a
151 :     <COMMENT>
152 :     <PROTOTY>
153 :     recv <ARG/ch/
154 :     </PROTOTY>
155 :     receives a message from the channel <ARG/ch/.
156 :     This operation blocks the calling thread until there is another
157 :     thread attempting a <VALREF/send/ operation on the channel <ARG/ch/.
158 :     <SPEC>
159 :     <VAL>sendEvt<TY>('a chan * 'a) -> unit event
160 :     <VAL>recvEvt<TY>'a chan -> 'a event
161 :     <COMMENT>
162 : monnier 106 <PP>
163 : monnier 7 These functions create event values to represent the <VALREF/send/
164 :     and <VALREF/recv/ operations.
165 :     <SPEC>
166 :     <VAL>sendPoll<TY>('a chan * 'a) -> bool
167 :     <COMMENT>
168 :     <PROTOTY>
169 :     send (<ARG/ch/, <ARG/a/)
170 :     </PROTOTY>
171 :     attempts to send the message <ARG/a/ on the synchronous channel <ARG/ch/.
172 :     If this operation can complete without blocking the calling thread, then
173 :     the message is sent and <CD/true/ is returned.
174 :     Otherwise, no communication is preformed and <CD/false/ is returned.
175 :     This function is not recommended for general use; it is provided
176 :     as an efficiency aid for certain kinds of protocols.
177 :     <SPEC>
178 :     <VAL>recvPoll<TY>'a chan -> 'a option
179 :     <COMMENT>
180 :     <PROTOTY>
181 :     recvPoll <ARG/ch/
182 :     </PROTOTY>
183 :     attempts to receive a message from the channel <ARG/ch/.
184 :     If there is no other thread offering to <VALREF/send/ a message
185 :     on <ARG/ch/, then this returns
186 :     <CONREF DOCUMENT=SML-BASIS-DOC STRID="Option"/NONE/, otherwise it
187 :     returns <CONREF DOCUMENT=SML-BASIS-DOC STRID="Option"/SOME/ wrapped
188 :     around the message.
189 :     This function is not recommended for general use; it is provided
190 :     as an efficiency aid for certain kinds of protocols.
191 :     <SPEC>
192 :     <VAL>wrap<TY>('a event * ('a -> 'b)) -> 'b event
193 :     <COMMENT>
194 :     <PROTOTY>
195 :     wrap (<ARG/ev/, <ARG/f/)
196 :     </PROTOTY>
197 :     wraps the post-synchronization action <ARG/f/ around the event
198 :     value <ARG/ev/.
199 :     <SPEC>
200 :     <VAL>wrapHandler<TY>('a event * (exn -> 'a event)) -> 'a event
201 :     <COMMENT>
202 :     <PROTOTY>
203 :     wrapHandler (<ARG/ev/, <ARG/f/)
204 :     </PROTOTY>
205 :     wraps the exception handler function <ARG/f/ around the event
206 :     value <ARG/ev/.
207 :     If, during execution of some post-synchronization action in
208 :     <ARG/ev/, an exception is raised, it will be caught and passed
209 :     to <ARG/f/.
210 :     Nesting of handlers works as would be expected: the innermost
211 :     handler is the one invoked.
212 :     Note that exceptions raised in the pre-synchronization actions in
213 :     <ARG/ev/ (i.e., actions defined by <VALREF/guard/ and <VALREF/withNack/)
214 :     are not handled by <ARG/f/.
215 :     <SPEC>
216 :     <VAL>guard<TY>(unit -> 'a event) -> 'a event
217 :     <COMMENT>
218 :     <PROTOTY>
219 :     guard <ARG/f/
220 :     </PROTOTY>
221 :     creates <IT>delayed</IT> event value from the function <ARG/f/.
222 :     When the resulting event value is synchronized on, the function
223 :     <ARG/f/ will be evaluated and the resulting event value will be
224 :     used in its place in the synchronization.
225 :     This provides a mechanism for implementing pre-synchronization
226 :     actions, such as sending a request to a server.
227 :     <SPEC>
228 :     <VAL>withNack<TY>(unit event -> 'a event) -> 'a event
229 :     <COMMENT>
230 :     <PROTOTY>
231 :     withNack <ARG/f/
232 :     </PROTOTY>
233 :     creates <IT>delayed</IT> event value from the function <ARG/f/.
234 :     As in the case of <VALREF/guard/, the function <ARG/f/ will be evaluated
235 :     at synchronization time and the resulting event value will be
236 :     used in its place in the synchronization.
237 :     Furthermore, when <ARG/f/ is evaluated, it is passed a <IT>negative
238 :     acknowledgement</IT> event as an argument.
239 :     If the event value that is returned from the evaluation of <ARG/f/
240 :     is <EM/not/ chosen in the synchronization, then the negative
241 :     event will be enabled.
242 :     This provides a mechanism for informing servers that a client has
243 :     aborted a transaction.
244 :     <SPEC>
245 :     <VAL>choose<TY>'a event list -> 'a event
246 :     <COMMENT>
247 :     <PROTOTY>
248 :     choose <ARG/l/
249 :     </PROTOTY>
250 :     constructs an event value that represents the non-deterministic
251 :     choice of the events in the list <ARG/l/.
252 :     <SPEC>
253 :     <VAL>sync<TY>'a event -> 'a
254 :     <COMMENT>
255 :     <PROTOTY>
256 :     sync <ARG/ev/
257 :     </PROTOTY>
258 :     synchronizes the calling thread on the event <ARG/ev/.
259 :     <SPEC>
260 :     <VAL>select<TY>'a event list -> 'a
261 :     <COMMENT>
262 :     <PROTOTY>
263 :     select <ARG/evs/
264 :     </PROTOTY>
265 :     synchronizes on the choice of a list of event values.
266 :     This is semantically equivalant to:
267 :     <CODE>
268 :     <VALREF/sync/ (<VALREF/choose/ <ARG/evs/)
269 :     </CODE>
270 :     but is more efficient.
271 :     <SPEC>
272 :     <VAL>never<TY>'a event
273 :     <COMMENT>
274 :     <PROTOTY>
275 :     never
276 :     </PROTOTY>
277 :     is an event value that is never enabled for synchronization.
278 :     It is semantically equivalant to the expression:
279 :     <CODE>
280 :     <VALREF/choose/ []
281 :     </CODE>
282 :     <SPEC>
283 :     <VAL>alwaysEvt<TY>'a -> 'a event
284 :     <COMMENT>
285 :     <PROTOTY>
286 :     alwaysEvt <ARG/a/
287 :     </PROTOTY>
288 :     creates an event value that is always enabled, and that returns
289 :     the value <ARG/a/ upon synchronization.
290 :     <SPEC>
291 :     <VAL>timeOutEvt<TY>Time.time -> unit event
292 :     <COMMENT>
293 :     <PROTOTY>
294 :     timeOutEvt <ARG/t/
295 :     </PROTOTY>
296 :     creates an event value that becomes enabled at the time
297 :     interval <ARG/t/ after synchronization.
298 :     For example, the expression:
299 :     <CODE>
300 :     <VALREF/sync/ (timeOutEvt (<VALREF DOCUMENT=SML-BASIS-DOC STRID="Time"/Time.fromSeconds/ 1))
301 :     </CODE>
302 :     will delay the calling thread for one second.
303 :     Note that the specified time interval is actually a minimum
304 :     waiting time, and the delay may be longer.
305 :     <SPEC>
306 :     <VAL>atTimeEvt<TY>Time.time -> unit event
307 :     <COMMENT>
308 :     <PROTOTY>
309 :     atTimeEvt <ARG/t/
310 :     </PROTOTY>
311 :     creates an event value that becomes enabled at the specified time
312 :     <ARG/t/.
313 :     </SIGBODY>
314 :     </STRUCTURE>
315 : monnier 106 </INTERFACE>

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