The Concurrent ML Reference Manual


The SyncVar structure

The SyncVar structure provides Id-style synchronous variables (or memory cells). These variables have two states: empty and full. 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 Put exception being raised. There are two kinds of synchronous variables: I-variables are write-once, while M-variables are mutable.


Synopsis

signature SYNC_VAR
structure SyncVar : SYNC_VAR

Interface

exception Put
type 'a ivar
val iVar : unit -> 'a ivar
val iPut : ('a ivar * 'a) -> unit
val iGet : 'a ivar -> 'a
val iGetEvt : 'a ivar -> 'a event
val iGetPoll : 'a ivar -> 'a option
val sameIVar : ('a ivar * 'a ivar) -> bool
type 'a mvar
val mVar : unit -> 'a mvar
val mVarInit : 'a -> 'a mvar
val mPut : ('a mvar * 'a) -> unit
val mTake : 'a mvar -> 'a
val mTakeEvt : 'a mvar -> 'a event
val mGet : 'a mvar -> 'a
val mGetEvt : 'a mvar -> 'a event
val mTakePoll : 'a mvar -> 'a option
val mGetPoll : 'a mvar -> 'a option
val mSwap : ('a mvar * 'a) -> 'a
val mSwapEvt : ('a mvar * 'a) -> 'a event
val sameMVar : ('a mvar * 'a mvar) -> bool

Description

exception Put
This exception is raised when an attempt is made to put a value into a value that is already full (see iPut and mPut).

type 'a ivar
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.

iVar ()
creates a new empty I-variable.

iPut (iv, x)
fills the I-variable iv with the value x. Any threads that are blocked on iv will be resumed. If iv already has a value in it, then the Put exception is raised.

iGet iv
returns the contents of the I-variable iv. If the variable is empty, then the calling thread blocks until the variable becomes full.

iGetEvt iv
returns an event-value that represents the iGet operation on iv.

val iGetPoll
This is a non-blocking version of iGet. If the corresponding blocking form would block, then it returns NONE; otherwise it returns SOME of the variable's contents.

sameIVar (iv1, iv2)
returns true, if the iv1 and iv2 are the same I-variable.

type 'a mvar
This is the type constructor for M-structured variables. Unlike ivar values, M-structured variables may be updated multiple times. Like I-variables, however, they may only be written if they are empty.

mVar ()
creates a new empty M-variable.

mVar x
creates a new M-variable initialized to x.

mPut (mv, x)
fills the M-variable mv with the value x. Any threads that are blocked on mv will be resumed. If mv already has a value in it, then the Put exception is raised.

mTake mv
removes and returns the contents of the M-variable mv making it empty. If the variable is already empty, then the calling thread is blocked until a value is available.

mTakeEvt mv
returns an event-value that represents the mTake operation on mv.

mGet mv
returns the contents of the M-variable mv without emptying the variable; if the variable is empty, then the thread blocks until a value is available. It is equivalent to the code:
let val x = mTake mv in mPut(mv, x); x end
	  


mGetEvt mv
returns an event-value that represents the mGet operation on mv.

val mTakePoll
val mGetPoll
These are non-blocking versions of mTake and mGet (respectively). If the corresponding blocking form would block, then they return NONE; otherwise they return SOME of the variable's contents.

mSwap (mv, newV)
puts the value newV into the M-variable mv and returns the previous contents. If the variable is empty, then the thread blocks until a value is available. It is equivalent to the code:
let val x = mTake mv in mPut(mv, newV); x end
	  
except that mSwap is executed atomically.

mSwapEvt mv
returns an event-value that represents the mSwap operation on mv and newV.

sameMVar (mv1, mv2)
returns true, if mv1 and mv2 are the same M-variable.


Discussion

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.

A disciplined use of M-variables can provide an atomic read-modify-write operation.

See Also

CML

[ INDEX | TOP | Parent | Root ]

Last Modified November 16, 1995
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies


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