doc/guide/src/ConcurrentML.adoc

   1 ConcurrentML
   2 ============
   3
   4 http://cml.cs.uchicago.edu/[Concurrent ML] is an SML concurrency
   5 library based on synchronous message passing.  MLton has an initial
   6 port of CML from SML/NJ, but is missing a thread-safe wrapper around
   7 the Basis Library and event-based equivalents to `IO` and `OS`
   8 functions.
   9
  10 All of the core CML functionality is present.
  11
  12 [source,sml]
  13 ----
  14 structure CML: CML
  15 structure SyncVar: SYNC_VAR
  16 structure Mailbox: MAILBOX
  17 structure Multicast: MULTICAST
  18 structure SimpleRPC: SIMPLE_RPC
  19 structure RunCML: RUN_CML
  20 ----
  21
  22 The `RUN_CML` signature is minimal.
  23
  24 [source,sml]
  25 ----
  26 signature RUN_CML =
  27    sig
  28       val isRunning: unit -> bool
  29       val doit: (unit -> unit) * Time.time option -> OS.Process.status
  30       val shutdown: OS.Process.status -> 'a
  31    end
  32 ----
  33
  34 MLton's `RunCML` structure does not include all of the cleanup and
  35 logging operations of SML/NJ's `RunCML` structure.  However, the
  36 implementation does include the `CML.timeOutEvt` and `CML.atTimeEvt`
  37 functions, and a preemptive scheduler that knows to sleep when there
  38 are no ready threads and some threads blocked on time events.
  39
  40 Because MLton does not wrap the Basis Library for CML, the "right" way
  41 to call a Basis Library function that is stateful is to wrap the call
  42 with `MLton.Thread.atomically`.
  43
  44 == Usage ==
  45
  46 * You can import the CML Library into an MLB file with:
  47 +
  48 [options="header"]
  49 |=====
  50 |MLB file|Description
  51 |`$(SML_LIB)/cml/cml.mlb`|
  52 |====
  53
  54 * If you are porting a project from SML/NJ's <:CompilationManager:> to
  55 MLton's <:MLBasis: ML Basis system> using `cm2mlb`, note that the
  56 following map is included by default:
  57 +
  58 ----
  59 # CML Library
  60 $cml                                    $(SML_LIB)/cml
  61 $cml/cml.cm                             $(SML_LIB)/cml/cml.mlb
  62 ----
  63 +
  64 This will automatically convert a `$cml/cml.cm` import in an input `.cm` file into a `$(SML_LIB)/cml/cml.mlb` import in the output `.mlb` file.
  65
  66 == Also see ==
  67
  68 * <:ConcurrentMLImplementation:>
  69 * <:eXene:>