The Concurrent ML Reference Manual


The CML structure


Synopsis

signature CML
structure CML : CML

Interface

type thread_id
type 'a chan
type 'a event
val version : {system : string, version_id : int list, date : string}
val banner : string
val spawnc : ('a -> unit) -> 'a -> thread_id
val spawn : (unit -> unit) -> thread_id
val yield : unit -> unit
val exit : unit -> 'a
val getTid : unit -> thread_id
val sameTid : (thread_id * thread_id) -> bool
val compareTid : (thread_id * thread_id) -> order
val hashTid : thread_id -> word
val tidToString : thread_id -> string
val joinEvt : thread_id -> unit event
val channel : unit -> 'a chan
val sameChannel : ('a chan * 'a chan) -> bool
val send : ('a chan * 'a) -> unit
val recv : 'a chan -> 'a
val sendEvt : ('a chan * 'a) -> unit event
val recvEvt : 'a chan -> 'a event
val sendPoll : ('a chan * 'a) -> bool
val recvPoll : 'a chan -> 'a option
val wrap : ('a event * ('a -> 'b)) -> 'b event
val wrapHandler : ('a event * (exn -> 'a event)) -> 'a event
val guard : (unit -> 'a event) -> 'a event
val withNack : (unit event -> 'a event) -> 'a event
val choose : 'a event list -> 'a event
val sync : 'a event -> 'a
val select : 'a event list -> 'a
val never : 'a event
val alwaysEvt : 'a -> 'a event
val timeOutEvt : Time.time -> unit event
val atTimeEvt : Time.time -> unit event

Description

type thread_id
Thread IDs are the unique IDs associated with CML threads. These IDs are in an unspecified total order that can be used to break cyclic depedencies (see compareTid).

type 'a chan
This is the type constructor for synchronous channels.

type 'a event
Event values are abstract representations of synchronous operations (so called first-class sychronous operations).

val version
val banner
These specify the version of CML in the same format as SML/NJ.

spawnc f x
spawn f
creates a new thread of control to evaluate the body of f. A new unique ID for the thread is created and returned.

val yield
This function can be used to implement an explicit context switch. Since CML is preemptively scheduled, it should never be necessary for user programs to call this function. It is mainly used for performance measurements.

exit ()
causes the calling thread to terminate.

getTid ()
returns the thread ID of the calling thread.

sameTid (tid1, tid2)
returns true, if the two thread IDs are the same ID.

compareTid (tid1, tid2)
compares the two thread IDs and returns their order in the total ordering of thread IDs. The precise semantics of this ordering is left unspecified, other than to say it is a total order.

hashTid tid
returns a hashing of the thread ID tid.

tidToString tid
returns a string representation of the thread ID tid.

joinEvt tid
creates an event value for synchronizing on the termination of the thread with the ID tid. There are three ways that a thread may terminate: the function that was passed to spawn may return; it may call the exit function, or it may have an uncaught exception. Note that joinEvt does not distinguish between these cases; it also does not become enabled if the named thread deadlocks (even if it is garbage collected).

channel ()
creates a new synchronous channel.

sameChannel (ch1, ch2)
returns true, if the two channels are the same channel.

send (ch, a)
sends the message a on the synchronous channel ch. This operation blocks the calling thread until there is another thread attempting a recv operation on the channel ch.

recv ch
receives a message from the channel ch. This operation blocks the calling thread until there is another thread attempting a send operation on the channel ch.

val sendEvt
val recvEvt
These functions create event values to represent the send and recv operations.

send (ch, a)
attempts to send the message a on the synchronous channel ch. If this operation can complete without blocking the calling thread, then the message is sent and true is returned. Otherwise, no communication is preformed and false is returned. This function is not recommended for general use; it is provided as an efficiency aid for certain kinds of protocols.

recvPoll ch
attempts to receive a message from the channel ch. If there is no other thread offering to send a message on ch, then this returns NONE, otherwise it returns SOME wrapped around the message. This function is not recommended for general use; it is provided as an efficiency aid for certain kinds of protocols.

wrap (ev, f)
wraps the post-synchronization action f around the event value ev.

wrapHandler (ev, f)
wraps the exception handler function f around the event value ev. If, during execution of some post-synchronization action in ev, an exception is raised, it will be caught and passed to f. Nesting of handlers works as would be expected: the innermost handler is the one invoked. Note that exceptions raised in the pre-synchronization actions in ev (i.e., actions defined by guard and withNack) are not handled by f.

guard f
creates delayed event value from the function f. When the resulting event value is synchronized on, the function f will be evaluated and the resulting event value will be used in its place in the synchronization. This provides a mechanism for implementing pre-synchronization actions, such as sending a request to a server.

withNack f
creates delayed event value from the function f. As in the case of guard, the function f will be evaluated at synchronization time and the resulting event value will be used in its place in the synchronization. Furthermore, when f is evaluated, it is passed a negative acknowledgement event as an argument. If the event value that is returned from the evaluation of f is not chosen in the synchronization, then the negative event will be enabled. This provides a mechanism for informing servers that a client has aborted a transaction.

choose l
constructs an event value that represents the non-deterministic choice of the events in the list l.

sync ev
synchronizes the calling thread on the event ev.

select evs
synchronizes on the choice of a list of event values. This is semantically equivalant to:
	    sync (choose evs)
	  
but is more efficient.

never
is an event value that is never enabled for synchronization. It is semantically equivalant to the expression:
	    choose []
	  


alwaysEvt a
creates an event value that is always enabled, and that returns the value a upon synchronization.

timeOutEvt t
creates an event value that becomes enabled at the time interval t after synchronization. For example, the expression:
	    sync (timeOutEvt (Time.fromSeconds 1))
	  
will delay the calling thread for one second. Note that the specified time interval is actually a minimum waiting time, and the delay may be longer.

atTimeEvt t
creates an event value that becomes enabled at the specified time t. For example, the expression:
	    sync (atTimeEvt (Date.toTime (Date.date {
		year = 2000, month = Date.Jan, day = 0,
		hour = 0, minute = 0, second = 0, 
		offset = NONE
	      })))
	  
blocks the calling thread until the beginning of the year 2000.


See Also

Option, Time

[ Top | Parent | Contents | Index | Root ]

Last Modified &date;
Comments to John Reppy.
Copyright © 1998 Bell Labs, Lucent Technologies


Click to toggle
does not end with </html> tag
does not end with </body> tag
The output has ended thus: n Reppy.</A></I><BR> Copyright &copy; 1998 Bell Labs, Lucent Technologies <BR> <HR> </BODY></HTML>