doc/guide/src/Stabilizers.adoc

   1 Stabilizers
   2 ===========
   3
   4 == Installation ==
   5
   6 * Stabilizers currently require the MLton sources, this should be fixed by the next release
   7
   8 == License ==
   9
  10 * Stabilizers are released under the MLton License
  11
  12 == Instructions ==
  13
  14 * Download and build a source copy of MLton
  15 * Extract the tar.gz file attached to this page
  16 * Some examples are provided in the "examples/" sub directory, more examples will be added to this page in the following week
  17
  18 == Bug reports / Suggestions ==
  19
  20 * Please send any errors you encounter to schatzp and lziarek at cs.purdue.edu
  21 * We are looking to expand the usability of stabilizers
  22 * Please send any suggestions and desired functionality to the above email addresses
  23
  24 == Note ==
  25
  26 * This is an alpha release. We expect to have another release shortly with added functionality soon
  27 * More documentation, such as signatures and descriptions of functionality, will be forthcoming
  28
  29
  30 == Documentation ==
  31
  32 [source,sml]
  33 ----
  34 signature STABLE =
  35   sig
  36      type checkpoint
  37
  38      val stable: ('a -> 'b) -> ('a -> 'b)
  39      val stabilize: unit -> 'a
  40
  41      val stableCP: (('a -> 'b) * (unit -> unit)) ->
  42                     (('a -> 'b) *  checkpoint)
  43      val stabilizeCP: checkpoint -> unit
  44
  45      val unmonitoredAssign: ('a ref * 'a) -> unit
  46      val monitoredAssign: ('a ref * 'a) -> unit
  47   end
  48 ----
  49
  50
  51 `Stable` provides functions to manage stable sections.
  52
  53 * `type checkpoint`
  54 +
  55 handle used to stabilize contexts other than the current one.
  56
  57 * `stable f`
  58 +
  59 returns a function identical to `f` that will execute within a stable section.
  60
  61 * `stabilize ()`
  62 +
  63 unrolls the effects made up to the current context to at least the
  64 nearest enclosing _stable_ section.  These effects may have propagated
  65 to other threads, so all affected threads are returned to a globally
  66 consistent previous state.  The return is undefined because control
  67 cannot resume after stabilize is called.
  68
  69 * `stableCP (f, comp)`
  70 +
  71 returns a function `f'` and checkpoint tag `cp`.  Function `f'` is
  72 identical to `f` but when applied will execute within a stable
  73 section.  `comp` will be executed if `f'` is later stabilized.  `cp`
  74 is used by `stabilizeCP` to stabilize a given checkpoint.
  75
  76 * `stabilizeCP cp`
  77 +
  78 same as stabilize except that the (possibly current) checkpoint to
  79 stabilize is provided.
  80
  81 * `unmonitoredAssign (r, v)`
  82 +
  83 standard assignment (`:=`).  The version of CML distributed rebinds
  84 `:=` to a monitored version so interesting effects can be recorded.
  85
  86 * `monitoredAssign (r, v)`
  87 +
  88 the assignment operator that should be used in programs that use
  89 stabilizers. `:=` is rebound to this by including CML.
  90
  91 == Download ==
  92
  93 * <!Attachment(Stabilizers,stabilizers_alpha_2006-10-09.tar.gz)>
  94
  95 == Also see ==
  96
  97 * <!Cite(ZiarekEtAl06)>