src/Doc/Implementation/ML.thy
author wenzelm
Mon, 18 Aug 2014 12:17:31 +0200
changeset 57978 8f4a332500e4
parent 57834 0d295e339f52
child 58555 7975676c08c0
permissions -rw-r--r--
Added tag Isabelle2014-RC4 for changeset 113b43b84412
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
57347
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
     1
(*:wrap=hard:maxLineLen=78:*)
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
     2
29755
d66b34e46bdf observe usual theory naming conventions;
wenzelm
parents: 29646
diff changeset
     3
theory "ML"
d66b34e46bdf observe usual theory naming conventions;
wenzelm
parents: 29646
diff changeset
     4
imports Base
d66b34e46bdf observe usual theory naming conventions;
wenzelm
parents: 29646
diff changeset
     5
begin
18538
88fe84d4d151 outline;
wenzelm
parents: 18537
diff changeset
     6
39822
0de42180febe basic setup for Chapter 0: Isabelle/ML;
wenzelm
parents: 36164
diff changeset
     7
chapter {* Isabelle/ML *}
20489
a684fc70d04e tentative appendix C;
wenzelm
parents: 18554
diff changeset
     8
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
     9
text {* Isabelle/ML is best understood as a certain culture based on
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    10
  Standard ML.  Thus it is not a new programming language, but a
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    11
  certain way to use SML at an advanced level within the Isabelle
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    12
  environment.  This covers a variety of aspects that are geared
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    13
  towards an efficient and robust platform for applications of formal
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    14
  logic with fully foundational proof construction --- according to
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    15
  the well-known \emph{LCF principle}.  There is specific
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    16
  infrastructure with library modules to address the needs of this
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    17
  difficult task.  For example, the raw parallel programming model of
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    18
  Poly/ML is presented as considerably more abstract concept of
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
    19
  \emph{futures}, which is then used to augment the inference
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
    20
  kernel, Isar theory and proof interpreter, and PIDE document management.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    21
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    22
  The main aspects of Isabelle/ML are introduced below.  These
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    23
  first-hand explanations should help to understand how proper
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    24
  Isabelle/ML is to be read and written, and to get access to the
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    25
  wealth of experience that is expressed in the source text and its
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    26
  history of changes.\footnote{See
54703
499f92dc6e45 more antiquotations;
wenzelm
parents: 54387
diff changeset
    27
  @{url "http://isabelle.in.tum.de/repos/isabelle"} for the full
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    28
  Mercurial history.  There are symbolic tags to refer to official
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    29
  Isabelle releases, as opposed to arbitrary \emph{tip} versions that
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    30
  merely reflect snapshots that are never really up-to-date.}  *}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    31
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
    32
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    33
section {* Style and orthography *}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    34
39879
wenzelm
parents: 39878
diff changeset
    35
text {* The sources of Isabelle/Isar are optimized for
wenzelm
parents: 39878
diff changeset
    36
  \emph{readability} and \emph{maintainability}.  The main purpose is
wenzelm
parents: 39878
diff changeset
    37
  to tell an informed reader what is really going on and how things
wenzelm
parents: 39878
diff changeset
    38
  really work.  This is a non-trivial aim, but it is supported by a
wenzelm
parents: 39878
diff changeset
    39
  certain style of writing Isabelle/ML that has emerged from long
wenzelm
parents: 39878
diff changeset
    40
  years of system development.\footnote{See also the interesting style
wenzelm
parents: 39878
diff changeset
    41
  guide for OCaml
54703
499f92dc6e45 more antiquotations;
wenzelm
parents: 54387
diff changeset
    42
  @{url "http://caml.inria.fr/resources/doc/guides/guidelines.en.html"}
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    43
  which shares many of our means and ends.}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    44
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    45
  The main principle behind any coding style is \emph{consistency}.
39879
wenzelm
parents: 39878
diff changeset
    46
  For a single author of a small program this merely means ``choose
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    47
  your style and stick to it''.  A complex project like Isabelle, with
39879
wenzelm
parents: 39878
diff changeset
    48
  long years of development and different contributors, requires more
wenzelm
parents: 39878
diff changeset
    49
  standardization.  A coding style that is changed every few years or
wenzelm
parents: 39878
diff changeset
    50
  with every new contributor is no style at all, because consistency
wenzelm
parents: 39878
diff changeset
    51
  is quickly lost.  Global consistency is hard to achieve, though.
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    52
  Nonetheless, one should always strive at least for local consistency
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    53
  of modules and sub-systems, without deviating from some general
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    54
  principles how to write Isabelle/ML.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    55
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    56
  In a sense, good coding style is like an \emph{orthography} for the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    57
  sources: it helps to read quickly over the text and see through the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    58
  main points, without getting distracted by accidental presentation
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    59
  of free-style code.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    60
*}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    61
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    62
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    63
subsection {* Header and sectioning *}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    64
39879
wenzelm
parents: 39878
diff changeset
    65
text {* Isabelle source files have a certain standardized header
wenzelm
parents: 39878
diff changeset
    66
  format (with precise spacing) that follows ancient traditions
wenzelm
parents: 39878
diff changeset
    67
  reaching back to the earliest versions of the system by Larry
40800
330eb65c9469 Parse.liberal_name for document antiquotations and attributes;
wenzelm
parents: 40508
diff changeset
    68
  Paulson.  See @{file "~~/src/Pure/thm.ML"}, for example.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    69
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    70
  The header includes at least @{verbatim Title} and @{verbatim
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    71
  Author} entries, followed by a prose description of the purpose of
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    72
  the module.  The latter can range from a single line to several
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    73
  paragraphs of explanations.
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    74
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    75
  The rest of the file is divided into sections, subsections,
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    76
  subsubsections, paragraphs etc.\ using a simple layout via ML
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    77
  comments as follows.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    78
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    79
\begin{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    80
(*** section ***)
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    81
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    82
(** subsection **)
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    83
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    84
(* subsubsection *)
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    85
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    86
(*short paragraph*)
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    87
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    88
(*
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    89
  long paragraph,
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    90
  with more text
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    91
*)
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    92
\end{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    93
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    94
  As in regular typography, there is some extra space \emph{before}
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
    95
  section headings that are adjacent to plain text, bit not other headings
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
    96
  as in the example above.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    97
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
    98
  \medskip The precise wording of the prose text given in these
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
    99
  headings is chosen carefully to introduce the main theme of the
39879
wenzelm
parents: 39878
diff changeset
   100
  subsequent formal ML text.
wenzelm
parents: 39878
diff changeset
   101
*}
wenzelm
parents: 39878
diff changeset
   102
wenzelm
parents: 39878
diff changeset
   103
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   104
subsection {* Naming conventions *}
39879
wenzelm
parents: 39878
diff changeset
   105
wenzelm
parents: 39878
diff changeset
   106
text {* Since ML is the primary medium to express the meaning of the
wenzelm
parents: 39878
diff changeset
   107
  source text, naming of ML entities requires special care.
wenzelm
parents: 39878
diff changeset
   108
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   109
  \paragraph{Notation.}  A name consists of 1--3 \emph{words} (rarely
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   110
  4, but not more) that are separated by underscore.  There are three
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   111
  variants concerning upper or lower case letters, which are used for
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   112
  certain ML categories as follows:
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   113
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   114
  \medskip
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   115
  \begin{tabular}{lll}
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   116
  variant & example & ML categories \\\hline
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   117
  lower-case & @{ML_text foo_bar} & values, types, record fields \\
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   118
  capitalized & @{ML_text Foo_Bar} & datatype constructors, structures, functors \\
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   119
  upper-case & @{ML_text FOO_BAR} & special values, exception constructors, signatures \\
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   120
  \end{tabular}
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   121
  \medskip
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   122
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   123
  For historical reasons, many capitalized names omit underscores,
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   124
  e.g.\ old-style @{ML_text FooBar} instead of @{ML_text Foo_Bar}.
47180
c14fda8fee38 improving spelling
bulwahn
parents: 46262
diff changeset
   125
  Genuine mixed-case names are \emph{not} used, because clear division
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   126
  of words is essential for readability.\footnote{Camel-case was
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   127
  invented to workaround the lack of underscore in some early
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   128
  non-ASCII character sets.  Later it became habitual in some language
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   129
  communities that are now strong in numbers.}
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   130
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   131
  A single (capital) character does not count as ``word'' in this
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   132
  respect: some Isabelle/ML names are suffixed by extra markers like
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   133
  this: @{ML_text foo_barT}.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   134
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   135
  Name variants are produced by adding 1--3 primes, e.g.\ @{ML_text
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   136
  foo'}, @{ML_text foo''}, or @{ML_text foo'''}, but not @{ML_text
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   137
  foo''''} or more.  Decimal digits scale better to larger numbers,
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   138
  e.g.\ @{ML_text foo0}, @{ML_text foo1}, @{ML_text foo42}.
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   139
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   140
  \paragraph{Scopes.}  Apart from very basic library modules, ML
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   141
  structures are not ``opened'', but names are referenced with
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   142
  explicit qualification, as in @{ML Syntax.string_of_term} for
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   143
  example.  When devising names for structures and their components it
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   144
  is important to aim at eye-catching compositions of both parts, because
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   145
  this is how they are seen in the sources and documentation.  For the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   146
  same reasons, aliases of well-known library functions should be
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   147
  avoided.
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   148
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   149
  Local names of function abstraction or case/let bindings are
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   150
  typically shorter, sometimes using only rudiments of ``words'',
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   151
  while still avoiding cryptic shorthands.  An auxiliary function
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   152
  called @{ML_text helper}, @{ML_text aux}, or @{ML_text f} is
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   153
  considered bad style.
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   154
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   155
  Example:
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   156
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   157
  \begin{verbatim}
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   158
  (* RIGHT *)
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   159
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   160
  fun print_foo ctxt foo =
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   161
    let
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   162
      fun print t = ... Syntax.string_of_term ctxt t ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   163
    in ... end;
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   164
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   165
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   166
  (* RIGHT *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   167
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   168
  fun print_foo ctxt foo =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   169
    let
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   170
      val string_of_term = Syntax.string_of_term ctxt;
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   171
      fun print t = ... string_of_term t ...
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   172
    in ... end;
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   173
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   174
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   175
  (* WRONG *)
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   176
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   177
  val string_of_term = Syntax.string_of_term;
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   178
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   179
  fun print_foo ctxt foo =
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   180
    let
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   181
      fun aux t = ... string_of_term ctxt t ...
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   182
    in ... end;
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   183
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   184
  \end{verbatim}
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   185
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   186
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   187
  \paragraph{Specific conventions.} Here are some specific name forms
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   188
  that occur frequently in the sources.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   189
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   190
  \begin{itemize}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   191
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   192
  \item A function that maps @{ML_text foo} to @{ML_text bar} is
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   193
  called @{ML_text foo_to_bar} or @{ML_text bar_of_foo} (never
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   194
  @{ML_text foo2bar}, nor @{ML_text bar_from_foo}, nor @{ML_text
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   195
  bar_for_foo}, nor @{ML_text bar4foo}).
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   196
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   197
  \item The name component @{ML_text legacy} means that the operation
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   198
  is about to be discontinued soon.
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   199
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   200
  \item The name component @{ML_text global} means that this works
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   201
  with the background theory instead of the regular local context
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   202
  (\secref{sec:context}), sometimes for historical reasons, sometimes
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   203
  due a genuine lack of locality of the concept involved, sometimes as
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   204
  a fall-back for the lack of a proper context in the application
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   205
  code.  Whenever there is a non-global variant available, the
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   206
  application should be migrated to use it with a proper local
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   207
  context.
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   208
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   209
  \item Variables of the main context types of the Isabelle/Isar
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   210
  framework (\secref{sec:context} and \chref{ch:local-theory}) have
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   211
  firm naming conventions as follows:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   212
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   213
  \begin{itemize}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   214
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   215
  \item theories are called @{ML_text thy}, rarely @{ML_text theory}
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   216
  (never @{ML_text thry})
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   217
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   218
  \item proof contexts are called @{ML_text ctxt}, rarely @{ML_text
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   219
  context} (never @{ML_text ctx})
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   220
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   221
  \item generic contexts are called @{ML_text context}
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   222
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   223
  \item local theories are called @{ML_text lthy}, except for local
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   224
  theories that are treated as proof context (which is a semantic
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   225
  super-type)
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   226
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   227
  \end{itemize}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   228
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   229
  Variations with primed or decimal numbers are always possible, as
56579
4c94f631c595 tuned spelling;
wenzelm
parents: 56420
diff changeset
   230
  well as semantic prefixes like @{ML_text foo_thy} or @{ML_text
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   231
  bar_ctxt}, but the base conventions above need to be preserved.
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   232
  This allows to emphasize their data flow via plain regular
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   233
  expressions in the text editor.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   234
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   235
  \item The main logical entities (\secref{ch:logic}) have established
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   236
  naming convention as follows:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   237
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   238
  \begin{itemize}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   239
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   240
  \item sorts are called @{ML_text S}
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   241
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   242
  \item types are called @{ML_text T}, @{ML_text U}, or @{ML_text
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   243
  ty} (never @{ML_text t})
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   244
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   245
  \item terms are called @{ML_text t}, @{ML_text u}, or @{ML_text
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   246
  tm} (never @{ML_text trm})
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   247
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   248
  \item certified types are called @{ML_text cT}, rarely @{ML_text
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   249
  T}, with variants as for types
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   250
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   251
  \item certified terms are called @{ML_text ct}, rarely @{ML_text
52733
wenzelm
parents: 52421
diff changeset
   252
  t}, with variants as for terms (never @{ML_text ctrm})
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   253
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   254
  \item theorems are called @{ML_text th}, or @{ML_text thm}
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   255
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   256
  \end{itemize}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   257
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   258
  Proper semantic names override these conventions completely.  For
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   259
  example, the left-hand side of an equation (as a term) can be called
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   260
  @{ML_text lhs} (not @{ML_text lhs_tm}).  Or a term that is known
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   261
  to be a variable can be called @{ML_text v} or @{ML_text x}.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   262
40310
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   263
  \item Tactics (\secref{sec:tactics}) are sufficiently important to
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   264
  have specific naming conventions.  The name of a basic tactic
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   265
  definition always has a @{ML_text "_tac"} suffix, the subgoal index
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   266
  (if applicable) is always called @{ML_text i}, and the goal state
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   267
  (if made explicit) is usually called @{ML_text st} instead of the
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   268
  somewhat misleading @{ML_text thm}.  Any other arguments are given
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   269
  before the latter two, and the general context is given first.
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   270
  Example:
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   271
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   272
  \begin{verbatim}
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   273
  fun my_tac ctxt arg1 arg2 i st = ...
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   274
  \end{verbatim}
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   275
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   276
  Note that the goal state @{ML_text st} above is rarely made
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   277
  explicit, if tactic combinators (tacticals) are used as usual.
a0698ec82e6e more on naming tactics;
wenzelm
parents: 40302
diff changeset
   278
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   279
  A tactic that requires a proof context needs to make that explicit as seen
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   280
  in the @{verbatim ctxt} argument above. Do not refer to the background
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   281
  theory of @{verbatim st} -- it is not a proper context, but merely a formal
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   282
  certificate.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   283
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   284
  \end{itemize}
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   285
*}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   286
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   287
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   288
subsection {* General source layout *}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   289
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   290
text {*
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   291
  The general Isabelle/ML source layout imitates regular type-setting
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   292
  conventions, augmented by the requirements for deeply nested expressions
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   293
  that are commonplace in functional programming.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   294
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   295
  \paragraph{Line length} is limited to 80 characters according to ancient
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   296
  standards, but we allow as much as 100 characters (not
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   297
  more).\footnote{Readability requires to keep the beginning of a line
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   298
  in view while watching its end.  Modern wide-screen displays do not
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   299
  change the way how the human brain works.  Sources also need to be
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   300
  printable on plain paper with reasonable font-size.} The extra 20
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   301
  characters acknowledge the space requirements due to qualified
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   302
  library references in Isabelle/ML.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   303
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   304
  \paragraph{White-space} is used to emphasize the structure of
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   305
  expressions, following mostly standard conventions for mathematical
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   306
  typesetting, as can be seen in plain {\TeX} or {\LaTeX}.  This
39879
wenzelm
parents: 39878
diff changeset
   307
  defines positioning of spaces for parentheses, punctuation, and
wenzelm
parents: 39878
diff changeset
   308
  infixes as illustrated here:
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   309
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   310
  \begin{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   311
  val x = y + z * (a + b);
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   312
  val pair = (a, b);
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   313
  val record = {foo = 1, bar = 2};
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   314
  \end{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   315
39879
wenzelm
parents: 39878
diff changeset
   316
  Lines are normally broken \emph{after} an infix operator or
wenzelm
parents: 39878
diff changeset
   317
  punctuation character.  For example:
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   318
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   319
  \begin{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   320
  val x =
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   321
    a +
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   322
    b +
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   323
    c;
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   324
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   325
  val tuple =
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   326
   (a,
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   327
    b,
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   328
    c);
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   329
  \end{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   330
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   331
  Some special infixes (e.g.\ @{ML_text "|>"}) work better at the
39879
wenzelm
parents: 39878
diff changeset
   332
  start of the line, but punctuation is always at the end.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   333
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   334
  Function application follows the tradition of @{text "\<lambda>"}-calculus,
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   335
  not informal mathematics.  For example: @{ML_text "f a b"} for a
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   336
  curried function, or @{ML_text "g (a, b)"} for a tupled function.
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   337
  Note that the space between @{ML_text g} and the pair @{ML_text
39879
wenzelm
parents: 39878
diff changeset
   338
  "(a, b)"} follows the important principle of
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   339
  \emph{compositionality}: the layout of @{ML_text "g p"} does not
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   340
  change when @{ML_text "p"} is refined to the concrete pair
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   341
  @{ML_text "(a, b)"}.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   342
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   343
  \paragraph{Indentation} uses plain spaces, never hard
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   344
  tabulators.\footnote{Tabulators were invented to move the carriage
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   345
  of a type-writer to certain predefined positions.  In software they
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   346
  could be used as a primitive run-length compression of consecutive
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   347
  spaces, but the precise result would depend on non-standardized
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   348
  text editor configuration.}
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   349
39879
wenzelm
parents: 39878
diff changeset
   350
  Each level of nesting is indented by 2 spaces, sometimes 1, very
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   351
  rarely 4, never 8 or any other odd number.
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   352
39879
wenzelm
parents: 39878
diff changeset
   353
  Indentation follows a simple logical format that only depends on the
wenzelm
parents: 39878
diff changeset
   354
  nesting depth, not the accidental length of the text that initiates
wenzelm
parents: 39878
diff changeset
   355
  a level of nesting.  Example:
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   356
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   357
  \begin{verbatim}
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   358
  (* RIGHT *)
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   359
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   360
  if b then
39879
wenzelm
parents: 39878
diff changeset
   361
    expr1_part1
wenzelm
parents: 39878
diff changeset
   362
    expr1_part2
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   363
  else
39879
wenzelm
parents: 39878
diff changeset
   364
    expr2_part1
wenzelm
parents: 39878
diff changeset
   365
    expr2_part2
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   366
39880
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   367
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   368
  (* WRONG *)
7deb6a741626 more on "Naming conventions";
wenzelm
parents: 39879
diff changeset
   369
39879
wenzelm
parents: 39878
diff changeset
   370
  if b then expr1_part1
wenzelm
parents: 39878
diff changeset
   371
            expr1_part2
wenzelm
parents: 39878
diff changeset
   372
  else expr2_part1
wenzelm
parents: 39878
diff changeset
   373
       expr2_part2
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   374
  \end{verbatim}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   375
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   376
  The second form has many problems: it assumes a fixed-width font
39879
wenzelm
parents: 39878
diff changeset
   377
  when viewing the sources, it uses more space on the line and thus
wenzelm
parents: 39878
diff changeset
   378
  makes it hard to observe its strict length limit (working against
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   379
  \emph{readability}), it requires extra editing to adapt the layout
39879
wenzelm
parents: 39878
diff changeset
   380
  to changes of the initial text (working against
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   381
  \emph{maintainability}) etc.
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   382
39879
wenzelm
parents: 39878
diff changeset
   383
  \medskip For similar reasons, any kind of two-dimensional or tabular
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   384
  layouts, ASCII-art with lines or boxes of asterisks etc.\ should be
39879
wenzelm
parents: 39878
diff changeset
   385
  avoided.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   386
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   387
  \paragraph{Complex expressions} that consist of multi-clausal
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   388
  function definitions, @{ML_text handle}, @{ML_text case},
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   389
  @{ML_text let} (and combinations) require special attention.  The
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   390
  syntax of Standard ML is quite ambitious and admits a lot of
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   391
  variance that can distort the meaning of the text.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   392
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   393
  Multiple clauses of @{ML_text fun}, @{ML_text fn}, @{ML_text handle},
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   394
  @{ML_text case} get extra indentation to indicate the nesting
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   395
  clearly.  Example:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   396
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   397
  \begin{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   398
  (* RIGHT *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   399
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   400
  fun foo p1 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   401
        expr1
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   402
    | foo p2 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   403
        expr2
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   404
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   405
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   406
  (* WRONG *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   407
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   408
  fun foo p1 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   409
    expr1
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   410
    | foo p2 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   411
    expr2
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   412
  \end{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   413
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   414
  Body expressions consisting of @{ML_text case} or @{ML_text let}
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   415
  require care to maintain compositionality, to prevent loss of
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   416
  logical indentation where it is especially important to see the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   417
  structure of the text.  Example:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   418
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   419
  \begin{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   420
  (* RIGHT *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   421
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   422
  fun foo p1 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   423
        (case e of
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   424
          q1 => ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   425
        | q2 => ...)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   426
    | foo p2 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   427
        let
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   428
          ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   429
        in
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   430
          ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   431
        end
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   432
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   433
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   434
  (* WRONG *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   435
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   436
  fun foo p1 = case e of
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   437
      q1 => ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   438
    | q2 => ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   439
    | foo p2 =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   440
    let
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   441
      ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   442
    in
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   443
      ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   444
    end
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   445
  \end{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   446
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   447
  Extra parentheses around @{ML_text case} expressions are optional,
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   448
  but help to analyse the nesting based on character matching in the
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   449
  text editor.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   450
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   451
  \medskip There are two main exceptions to the overall principle of
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   452
  compositionality in the layout of complex expressions.
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   453
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   454
  \begin{enumerate}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   455
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   456
  \item @{ML_text "if"} expressions are iterated as if ML had multi-branch
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   457
  conditionals, e.g.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   458
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   459
  \begin{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   460
  (* RIGHT *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   461
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   462
  if b1 then e1
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   463
  else if b2 then e2
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   464
  else e3
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   465
  \end{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   466
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   467
  \item @{ML_text fn} abstractions are often layed-out as if they
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   468
  would lack any structure by themselves.  This traditional form is
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   469
  motivated by the possibility to shift function arguments back and
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   470
  forth wrt.\ additional combinators.  Example:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   471
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   472
  \begin{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   473
  (* RIGHT *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   474
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   475
  fun foo x y = fold (fn z =>
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   476
    expr)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   477
  \end{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   478
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   479
  Here the visual appearance is that of three arguments @{ML_text x},
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   480
  @{ML_text y}, @{ML_text z} in a row.
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   481
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   482
  \end{enumerate}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   483
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   484
  Such weakly structured layout should be use with great care.  Here
40153
wenzelm
parents: 40149
diff changeset
   485
  are some counter-examples involving @{ML_text let} expressions:
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   486
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   487
  \begin{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   488
  (* WRONG *)
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   489
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   490
  fun foo x = let
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   491
      val y = ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   492
    in ... end
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   493
41162
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   494
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   495
  (* WRONG *)
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   496
40153
wenzelm
parents: 40149
diff changeset
   497
  fun foo x = let
wenzelm
parents: 40149
diff changeset
   498
    val y = ...
wenzelm
parents: 40149
diff changeset
   499
  in ... end
wenzelm
parents: 40149
diff changeset
   500
41162
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   501
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   502
  (* WRONG *)
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   503
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   504
  fun foo x =
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   505
  let
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   506
    val y = ...
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   507
  in ... end
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   508
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   509
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   510
  (* WRONG *)
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   511
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   512
  fun foo x =
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   513
    let
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   514
      val y = ...
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   515
    in
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   516
      ... end
39881
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   517
  \end{verbatim}
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   518
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   519
  \medskip In general the source layout is meant to emphasize the
40aee0b95ddf more on "Style and orthography";
wenzelm
parents: 39880
diff changeset
   520
  structure of complex language expressions, not to pretend that SML
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   521
  had a completely different syntax (say that of Haskell, Scala, Java).
39878
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   522
*}
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   523
31dd361a3060 more on "Style and orthography";
wenzelm
parents: 39875
diff changeset
   524
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   525
section {* ML embedded into Isabelle/Isar *}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   526
39824
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   527
text {* ML and Isar are intertwined via an open-ended bootstrap
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   528
  process that provides more and more programming facilities and
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   529
  logical content in an alternating manner.  Bootstrapping starts from
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   530
  the raw environment of existing implementations of Standard ML
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   531
  (mainly Poly/ML, but also SML/NJ).
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   532
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   533
  Isabelle/Pure marks the point where the raw ML toplevel is superseded by
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   534
  Isabelle/ML within the Isar theory and proof language, with a uniform
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   535
  context for arbitrary ML values (see also \secref{sec:context}). This formal
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   536
  environment holds ML compiler bindings, logical entities, and many other
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   537
  things.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   538
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   539
  Object-logics like Isabelle/HOL are built within the Isabelle/ML/Isar
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   540
  environment by introducing suitable theories with associated ML modules,
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   541
  either inlined within @{verbatim ".thy"} files, or as separate @{verbatim
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   542
  ".ML"} files that are loading from some theory. Thus Isabelle/HOL is defined
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   543
  as a regular user-space application within the Isabelle framework. Further
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   544
  add-on tools can be implemented in ML within the Isar context in the same
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   545
  manner: ML is part of the standard repertoire of Isabelle, and there is no
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   546
  distinction between ``users'' and ``developers'' in this respect.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   547
*}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   548
39824
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   549
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   550
subsection {* Isar ML commands *}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   551
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   552
text {*
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   553
  The primary Isar source language provides facilities to ``open a window'' to
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   554
  the underlying ML compiler. Especially see the Isar commands @{command_ref
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   555
  "ML_file"} and @{command_ref "ML"}: both work the same way, but the source
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   556
  text is provided differently, via a file vs.\ inlined, respectively. Apart
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   557
  from embedding ML into the main theory definition like that, there are many
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   558
  more commands that refer to ML source, such as @{command_ref setup} or
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   559
  @{command_ref declaration}. Even more fine-grained embedding of ML into Isar
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   560
  is encountered in the proof method @{method_ref tactic}, which refines the
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   561
  pending goal state via a given expression of type @{ML_type tactic}.
39824
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   562
*}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   563
39824
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   564
text %mlex {* The following artificial example demonstrates some ML
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   565
  toplevel declarations within the implicit Isar theory context.  This
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   566
  is regular functional programming without referring to logical
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   567
  entities yet.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   568
*}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   569
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   570
ML {*
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   571
  fun factorial 0 = 1
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   572
    | factorial n = n * factorial (n - 1)
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   573
*}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   574
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   575
text {* Here the ML environment is already managed by Isabelle, i.e.\
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
   576
  the @{ML factorial} function is not yet accessible in the preceding
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
   577
  paragraph, nor in a different theory that is independent from the
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
   578
  current one in the import hierarchy.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   579
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   580
  Removing the above ML declaration from the source text will remove any trace
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   581
  of this definition, as expected. The Isabelle/ML toplevel environment is
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   582
  managed in a \emph{stateless} way: in contrast to the raw ML toplevel, there
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   583
  are no global side-effects involved here.\footnote{Such a stateless
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   584
  compilation environment is also a prerequisite for robust parallel
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   585
  compilation within independent nodes of the implicit theory development
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   586
  graph.}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   587
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   588
  \medskip The next example shows how to embed ML into Isar proofs, using
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   589
  @{command_ref "ML_prf"} instead of Instead of @{command_ref "ML"}.
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   590
  As illustrated below, the effect on the ML environment is local to
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   591
  the whole proof body, but ignoring the block structure.
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   592
*}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   593
40964
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   594
notepad
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   595
begin
39851
7219a771ab63 more examples;
wenzelm
parents: 39850
diff changeset
   596
  ML_prf %"ML" {* val a = 1 *}
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   597
  {
39851
7219a771ab63 more examples;
wenzelm
parents: 39850
diff changeset
   598
    ML_prf %"ML" {* val b = a + 1 *}
39824
679075565542 misc tuning;
wenzelm
parents: 39823
diff changeset
   599
  } -- {* Isar block structure ignored by ML environment *}
39851
7219a771ab63 more examples;
wenzelm
parents: 39850
diff changeset
   600
  ML_prf %"ML" {* val c = b + 1 *}
40964
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   601
end
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   602
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
   603
text {* By side-stepping the normal scoping rules for Isar proof
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   604
  blocks, embedded ML code can refer to the different contexts and
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   605
  manipulate corresponding entities, e.g.\ export a fact from a block
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   606
  context.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   607
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
   608
  \medskip Two further ML commands are useful in certain situations:
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   609
  @{command_ref ML_val} and @{command_ref ML_command} are \emph{diagnostic} in
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   610
  the sense that there is no effect on the underlying environment, and can
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   611
  thus be used anywhere. The examples below produce long strings of digits by
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   612
  invoking @{ML factorial}: @{command ML_val} takes care of printing the ML
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   613
  toplevel result, but @{command ML_command} is silent so we produce an
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   614
  explicit output message.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   615
*}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   616
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   617
ML_val {* factorial 100 *}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   618
ML_command {* writeln (string_of_int (factorial 100)) *}
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   619
40964
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   620
notepad
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   621
begin
52417
wenzelm
parents: 52416
diff changeset
   622
  ML_val {* factorial 100 *}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   623
  ML_command {* writeln (string_of_int (factorial 100)) *}
40964
482a8334ee9e prefer 'notepad' over 'example_proof';
wenzelm
parents: 40800
diff changeset
   624
end
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   625
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   626
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   627
subsection {* Compile-time context *}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   628
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   629
text {* Whenever the ML compiler is invoked within Isabelle/Isar, the
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   630
  formal context is passed as a thread-local reference variable.  Thus
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   631
  ML code may access the theory context during compilation, by reading
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   632
  or writing the (local) theory under construction.  Note that such
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   633
  direct access to the compile-time context is rare.  In practice it
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   634
  is typically done via some derived ML functions instead.
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   635
*}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   636
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   637
text %mlref {*
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   638
  \begin{mldecls}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   639
  @{index_ML ML_Context.the_generic_context: "unit -> Context.generic"} \\
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   640
  @{index_ML "Context.>>": "(Context.generic -> Context.generic) -> unit"} \\
56199
8e8d28ed7529 tuned signature -- rearranged modules;
wenzelm
parents: 55838
diff changeset
   641
  @{index_ML ML_Thms.bind_thms: "string * thm list -> unit"} \\
8e8d28ed7529 tuned signature -- rearranged modules;
wenzelm
parents: 55838
diff changeset
   642
  @{index_ML ML_Thms.bind_thm: "string * thm -> unit"} \\
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   643
  \end{mldecls}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   644
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   645
  \begin{description}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   646
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   647
  \item @{ML "ML_Context.the_generic_context ()"} refers to the theory
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   648
  context of the ML toplevel --- at compile time.  ML code needs to
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   649
  take care to refer to @{ML "ML_Context.the_generic_context ()"}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   650
  correctly.  Recall that evaluation of a function body is delayed
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   651
  until actual run-time.
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   652
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   653
  \item @{ML "Context.>>"}~@{text f} applies context transformation
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   654
  @{text f} to the implicit context of the ML toplevel.
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   655
56199
8e8d28ed7529 tuned signature -- rearranged modules;
wenzelm
parents: 55838
diff changeset
   656
  \item @{ML ML_Thms.bind_thms}~@{text "(name, thms)"} stores a list of
39850
f4c614ece7ed moved bind_thm(s) to implementation manual;
wenzelm
parents: 39835
diff changeset
   657
  theorems produced in ML both in the (global) theory context and the
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   658
  ML toplevel, associating it with the provided name.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   659
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   660
  \item @{ML ML_Thms.bind_thm} is similar to @{ML ML_Thms.bind_thms} but
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   661
  refers to a singleton fact.
39850
f4c614ece7ed moved bind_thm(s) to implementation manual;
wenzelm
parents: 39835
diff changeset
   662
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   663
  \end{description}
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   664
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   665
  It is important to note that the above functions are really
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   666
  restricted to the compile time, even though the ML compiler is
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   667
  invoked at run-time.  The majority of ML code either uses static
39825
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   668
  antiquotations (\secref{sec:ML-antiq}) or refers to the theory or
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   669
  proof context at run-time, by explicit functional abstraction.
f9066b94bf07 eliminated fancy \ML logo for the sake of simpler source text (less dependence on LaTeX);
wenzelm
parents: 39824
diff changeset
   670
*}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   671
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   672
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   673
subsection {* Antiquotations \label{sec:ML-antiq} *}
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   674
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   675
text {* A very important consequence of embedding ML into Isar is the
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   676
  concept of \emph{ML antiquotation}.  The standard token language of
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   677
  ML is augmented by special syntactic entities of the following form:
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   678
55112
b1a5d603fd12 prefer rail cartouche -- avoid back-slashed quotes;
wenzelm
parents: 54703
diff changeset
   679
  @{rail \<open>
53167
4e7ddd76e632 discontinued unused antiquotation blocks;
wenzelm
parents: 53163
diff changeset
   680
  @{syntax_def antiquote}: '@{' nameref args '}'
55112
b1a5d603fd12 prefer rail cartouche -- avoid back-slashed quotes;
wenzelm
parents: 54703
diff changeset
   681
  \<close>}
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   682
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   683
  Here @{syntax nameref} and @{syntax args} are outer syntax categories, as
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   684
  defined in \cite{isabelle-isar-ref}.
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   685
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   686
  \medskip A regular antiquotation @{text "@{name args}"} processes
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   687
  its arguments by the usual means of the Isar source language, and
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   688
  produces corresponding ML source text, either as literal
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   689
  \emph{inline} text (e.g.\ @{text "@{term t}"}) or abstract
39827
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   690
  \emph{value} (e.g. @{text "@{thm th}"}).  This pre-compilation
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   691
  scheme allows to refer to formal entities in a robust manner, with
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   692
  proper static scoping and with some degree of logical checking of
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   693
  small portions of the code.
d829ce302ca4 basic setup for ML antiquotations -- with rail diagrams;
wenzelm
parents: 39825
diff changeset
   694
*}
39823
61e7935a6858 more on Isabelle/ML;
wenzelm
parents: 39822
diff changeset
   695
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
   696
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   697
subsection {* Printing ML values *}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   698
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   699
text {* The ML compiler knows about the structure of values according
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   700
  to their static type, and can print them in the manner of its
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   701
  toplevel, although the details are non-portable.  The
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   702
  antiquotations @{ML_antiquotation_def "make_string"} and
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   703
  @{ML_antiquotation_def "print"} provide a quasi-portable way to
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   704
  refer to this potential capability of the underlying ML system in
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   705
  generic Isabelle/ML sources.
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   706
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   707
  This is occasionally useful for diagnostic or demonstration
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   708
  purposes.  Note that production-quality tools require proper
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   709
  user-level error messages, avoiding raw ML values in the output. *}
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   710
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   711
text %mlantiq {*
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   712
  \begin{matharray}{rcl}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   713
  @{ML_antiquotation_def "make_string"} & : & @{text ML_antiquotation} \\
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   714
  @{ML_antiquotation_def "print"} & : & @{text ML_antiquotation} \\
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   715
  \end{matharray}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   716
55112
b1a5d603fd12 prefer rail cartouche -- avoid back-slashed quotes;
wenzelm
parents: 54703
diff changeset
   717
  @{rail \<open>
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   718
  @@{ML_antiquotation make_string}
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   719
  ;
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   720
  @@{ML_antiquotation print} @{syntax name}?
55112
b1a5d603fd12 prefer rail cartouche -- avoid back-slashed quotes;
wenzelm
parents: 54703
diff changeset
   721
  \<close>}
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   722
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   723
  \begin{description}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   724
57832
5b48f2047c24 clarified compile-time use of ML_print_depth;
wenzelm
parents: 57421
diff changeset
   725
  \item @{text "@{make_string}"} inlines a function to print arbitrary values
5b48f2047c24 clarified compile-time use of ML_print_depth;
wenzelm
parents: 57421
diff changeset
   726
  similar to the ML toplevel. The result is compiler dependent and may fall
5b48f2047c24 clarified compile-time use of ML_print_depth;
wenzelm
parents: 57421
diff changeset
   727
  back on "?" in certain situations. The value of configuration option
57834
0d295e339f52 prefer dynamic ML_print_depth if context happens to be available;
wenzelm
parents: 57832
diff changeset
   728
  @{attribute_ref ML_print_depth} determines further details of output.
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   729
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   730
  \item @{text "@{print f}"} uses the ML function @{text "f: string ->
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   731
  unit"} to output the result of @{text "@{make_string}"} above,
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   732
  together with the source position of the antiquotation.  The default
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   733
  output function is @{ML writeln}.
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   734
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   735
  \end{description}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   736
*}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   737
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   738
text %mlex {* The following artificial examples show how to produce
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   739
  adhoc output of ML values for debugging purposes. *}
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   740
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   741
ML {*
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   742
  val x = 42;
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   743
  val y = true;
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   744
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   745
  writeln (@{make_string} {x = x, y = y});
56399
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   746
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   747
  @{print} {x = x, y = y};
386e4cb7ad68 added ML antiquotation @{print};
wenzelm
parents: 56303
diff changeset
   748
  @{print tracing} {x = x, y = y};
51636
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   749
*}
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   750
e49bf0be79ba document @{make_string}, cf. NEWS of Isabelle2009-2 (June 2010);
wenzelm
parents: 51295
diff changeset
   751
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   752
section {* Canonical argument order \label{sec:canonical-argument-order} *}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   753
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   754
text {* Standard ML is a language in the tradition of @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   755
  "\<lambda>"}-calculus and \emph{higher-order functional programming},
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   756
  similar to OCaml, Haskell, or Isabelle/Pure and HOL as logical
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   757
  languages.  Getting acquainted with the native style of representing
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   758
  functions in that setting can save a lot of extra boiler-plate of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   759
  redundant shuffling of arguments, auxiliary abstractions etc.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   760
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   761
  Functions are usually \emph{curried}: the idea of turning arguments
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   762
  of type @{text "\<tau>\<^sub>i"} (for @{text "i \<in> {1, \<dots> n}"}) into a result of
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   763
  type @{text "\<tau>"} is represented by the iterated function space
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   764
  @{text "\<tau>\<^sub>1 \<rightarrow> \<dots> \<rightarrow> \<tau>\<^sub>n \<rightarrow> \<tau>"}.  This is isomorphic to the well-known
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   765
  encoding via tuples @{text "\<tau>\<^sub>1 \<times> \<dots> \<times> \<tau>\<^sub>n \<rightarrow> \<tau>"}, but the curried
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   766
  version fits more smoothly into the basic calculus.\footnote{The
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   767
  difference is even more significant in HOL, because the redundant
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   768
  tuple structure needs to be accommodated extraneous proof steps.}
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   769
56594
e3a06699a13f tuned spelling;
wenzelm
parents: 56579
diff changeset
   770
  Currying gives some flexibility due to \emph{partial application}.  A
53071
wenzelm
parents: 52733
diff changeset
   771
  function @{text "f: \<tau>\<^sub>1 \<rightarrow> \<tau>\<^sub>2 \<rightarrow> \<tau>"} can be applied to @{text "x: \<tau>\<^sub>1"}
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   772
  and the remaining @{text "(f x): \<tau>\<^sub>2 \<rightarrow> \<tau>"} passed to another function
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   773
  etc.  How well this works in practice depends on the order of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   774
  arguments.  In the worst case, arguments are arranged erratically,
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   775
  and using a function in a certain situation always requires some
56579
4c94f631c595 tuned spelling;
wenzelm
parents: 56420
diff changeset
   776
  glue code.  Thus we would get exponentially many opportunities to
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   777
  decorate the code with meaningless permutations of arguments.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   778
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   779
  This can be avoided by \emph{canonical argument order}, which
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   780
  observes certain standard patterns and minimizes adhoc permutations
40229
wenzelm
parents: 40153
diff changeset
   781
  in their application.  In Isabelle/ML, large portions of text can be
52416
wenzelm
parents: 51636
diff changeset
   782
  written without auxiliary operations like @{text "swap: \<alpha> \<times> \<beta> \<rightarrow> \<beta> \<times>
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   783
  \<alpha>"} or @{text "C: (\<alpha> \<rightarrow> \<beta> \<rightarrow> \<gamma>) \<rightarrow> (\<beta> \<rightarrow> \<alpha> \<rightarrow> \<gamma>)"} (the latter is not
52416
wenzelm
parents: 51636
diff changeset
   784
  present in the Isabelle/ML library).
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   785
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   786
  \medskip The main idea is that arguments that vary less are moved
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   787
  further to the left than those that vary more.  Two particularly
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   788
  important categories of functions are \emph{selectors} and
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   789
  \emph{updates}.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   790
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   791
  The subsequent scheme is based on a hypothetical set-like container
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   792
  of type @{text "\<beta>"} that manages elements of type @{text "\<alpha>"}.  Both
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   793
  the names and types of the associated operations are canonical for
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   794
  Isabelle/ML.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   795
52416
wenzelm
parents: 51636
diff changeset
   796
  \begin{center}
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   797
  \begin{tabular}{ll}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   798
  kind & canonical name and type \\\hline
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   799
  selector & @{text "member: \<beta> \<rightarrow> \<alpha> \<rightarrow> bool"} \\
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   800
  update & @{text "insert: \<alpha> \<rightarrow> \<beta> \<rightarrow> \<beta>"} \\
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   801
  \end{tabular}
52416
wenzelm
parents: 51636
diff changeset
   802
  \end{center}
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   803
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   804
  Given a container @{text "B: \<beta>"}, the partially applied @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   805
  "member B"} is a predicate over elements @{text "\<alpha> \<rightarrow> bool"}, and
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   806
  thus represents the intended denotation directly.  It is customary
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   807
  to pass the abstract predicate to further operations, not the
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   808
  concrete container.  The argument order makes it easy to use other
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   809
  combinators: @{text "forall (member B) list"} will check a list of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   810
  elements for membership in @{text "B"} etc. Often the explicit
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   811
  @{text "list"} is pointless and can be contracted to @{text "forall
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   812
  (member B)"} to get directly a predicate again.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   813
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   814
  In contrast, an update operation varies the container, so it moves
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   815
  to the right: @{text "insert a"} is a function @{text "\<beta> \<rightarrow> \<beta>"} to
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   816
  insert a value @{text "a"}.  These can be composed naturally as
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   817
  @{text "insert c \<circ> insert b \<circ> insert a"}.  The slightly awkward
40229
wenzelm
parents: 40153
diff changeset
   818
  inversion of the composition order is due to conventional
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   819
  mathematical notation, which can be easily amended as explained
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   820
  below.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   821
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   822
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   823
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   824
subsection {* Forward application and composition *}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   825
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   826
text {* Regular function application and infix notation works best for
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   827
  relatively deeply structured expressions, e.g.\ @{text "h (f x y + g
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   828
  z)"}.  The important special case of \emph{linear transformation}
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   829
  applies a cascade of functions @{text "f\<^sub>n (\<dots> (f\<^sub>1 x))"}.  This
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   830
  becomes hard to read and maintain if the functions are themselves
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   831
  given as complex expressions.  The notation can be significantly
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   832
  improved by introducing \emph{forward} versions of application and
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   833
  composition as follows:
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   834
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   835
  \medskip
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   836
  \begin{tabular}{lll}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   837
  @{text "x |> f"} & @{text "\<equiv>"} & @{text "f x"} \\
41162
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   838
  @{text "(f #> g) x"} & @{text "\<equiv>"} & @{text "x |> f |> g"} \\
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   839
  \end{tabular}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   840
  \medskip
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   841
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   842
  This enables to write conveniently @{text "x |> f\<^sub>1 |> \<dots> |> f\<^sub>n"} or
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   843
  @{text "f\<^sub>1 #> \<dots> #> f\<^sub>n"} for its functional abstraction over @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   844
  "x"}.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   845
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   846
  \medskip There is an additional set of combinators to accommodate
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   847
  multiple results (via pairs) that are passed on as multiple
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   848
  arguments (via currying).
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   849
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   850
  \medskip
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   851
  \begin{tabular}{lll}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   852
  @{text "(x, y) |-> f"} & @{text "\<equiv>"} & @{text "f x y"} \\
41162
2181c47a02fe more correct ML snippets that are unchecked;
wenzelm
parents: 40964
diff changeset
   853
  @{text "(f #-> g) x"} & @{text "\<equiv>"} & @{text "x |> f |-> g"} \\
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   854
  \end{tabular}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   855
  \medskip
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   856
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   857
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   858
text %mlref {*
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   859
  \begin{mldecls}
46262
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
   860
  @{index_ML_op "|> ": "'a * ('a -> 'b) -> 'b"} \\
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
   861
  @{index_ML_op "|-> ": "('c * 'a) * ('c -> 'a -> 'b) -> 'b"} \\
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
   862
  @{index_ML_op "#> ": "('a -> 'b) * ('b -> 'c) -> 'a -> 'c"} \\
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
   863
  @{index_ML_op "#-> ": "('a -> 'c * 'b) * ('c -> 'b -> 'd) -> 'a -> 'd"} \\
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   864
  \end{mldecls}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   865
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   866
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   867
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   868
subsection {* Canonical iteration *}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   869
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   870
text {* As explained above, a function @{text "f: \<alpha> \<rightarrow> \<beta> \<rightarrow> \<beta>"} can be
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   871
  understood as update on a configuration of type @{text "\<beta>"},
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   872
  parameterized by an argument of type @{text "\<alpha>"}.  Given @{text "a: \<alpha>"}
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   873
  the partial application @{text "(f a): \<beta> \<rightarrow> \<beta>"} operates
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   874
  homogeneously on @{text "\<beta>"}.  This can be iterated naturally over a
53071
wenzelm
parents: 52733
diff changeset
   875
  list of parameters @{text "[a\<^sub>1, \<dots>, a\<^sub>n]"} as @{text "f a\<^sub>1 #> \<dots> #> f a\<^sub>n"}.
wenzelm
parents: 52733
diff changeset
   876
  The latter expression is again a function @{text "\<beta> \<rightarrow> \<beta>"}.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   877
  It can be applied to an initial configuration @{text "b: \<beta>"} to
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   878
  start the iteration over the given list of arguments: each @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   879
  "a"} in @{text "a\<^sub>1, \<dots>, a\<^sub>n"} is applied consecutively by updating a
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   880
  cumulative configuration.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   881
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   882
  The @{text fold} combinator in Isabelle/ML lifts a function @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   883
  "f"} as above to its iterated version over a list of arguments.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   884
  Lifting can be repeated, e.g.\ @{text "(fold \<circ> fold) f"} iterates
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   885
  over a list of lists as expected.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   886
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   887
  The variant @{text "fold_rev"} works inside-out over the list of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   888
  arguments, such that @{text "fold_rev f \<equiv> fold f \<circ> rev"} holds.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   889
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   890
  The @{text "fold_map"} combinator essentially performs @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   891
  "fold"} and @{text "map"} simultaneously: each application of @{text
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   892
  "f"} produces an updated configuration together with a side-result;
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   893
  the iteration collects all such side-results as a separate list.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   894
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   895
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   896
text %mlref {*
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   897
  \begin{mldecls}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   898
  @{index_ML fold: "('a -> 'b -> 'b) -> 'a list -> 'b -> 'b"} \\
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   899
  @{index_ML fold_rev: "('a -> 'b -> 'b) -> 'a list -> 'b -> 'b"} \\
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   900
  @{index_ML fold_map: "('a -> 'b -> 'c * 'b) -> 'a list -> 'b -> 'c list * 'b"} \\
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   901
  \end{mldecls}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   902
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   903
  \begin{description}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   904
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   905
  \item @{ML fold}~@{text f} lifts the parametrized update function
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   906
  @{text "f"} to a list of parameters.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   907
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   908
  \item @{ML fold_rev}~@{text "f"} is similar to @{ML fold}~@{text
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   909
  "f"}, but works inside-out, as if the list would be reversed.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   910
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   911
  \item @{ML fold_map}~@{text "f"} lifts the parametrized update
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   912
  function @{text "f"} (with side-result) to a list of parameters and
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   913
  cumulative side-results.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   914
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   915
  \end{description}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   916
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   917
  \begin{warn}
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   918
  The literature on functional programming provides a confusing multitude of
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   919
  combinators called @{text "foldl"}, @{text "foldr"} etc. SML97 provides its
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   920
  own variations as @{ML List.foldl} and @{ML List.foldr}, while the classic
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   921
  Isabelle library also has the historic @{ML Library.foldl} and @{ML
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   922
  Library.foldr}. To avoid unnecessary complication, all these historical
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   923
  versions should be ignored, and the canonical @{ML fold} (or @{ML fold_rev})
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   924
  used exclusively.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   925
  \end{warn}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   926
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   927
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   928
text %mlex {* The following example shows how to fill a text buffer
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   929
  incrementally by adding strings, either individually or from a given
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   930
  list.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   931
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   932
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   933
ML {*
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   934
  val s =
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   935
    Buffer.empty
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   936
    |> Buffer.add "digits: "
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   937
    |> fold (Buffer.add o string_of_int) (0 upto 9)
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   938
    |> Buffer.content;
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   939
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   940
  @{assert} (s = "digits: 0123456789");
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   941
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   942
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   943
text {* Note how @{ML "fold (Buffer.add o string_of_int)"} above saves
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   944
  an extra @{ML "map"} over the given list.  This kind of peephole
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   945
  optimization reduces both the code size and the tree structures in
52416
wenzelm
parents: 51636
diff changeset
   946
  memory (``deforestation''), but it requires some practice to read
wenzelm
parents: 51636
diff changeset
   947
  and write fluently.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   948
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   949
  \medskip The next example elaborates the idea of canonical
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   950
  iteration, demonstrating fast accumulation of tree content using a
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   951
  text buffer.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   952
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   953
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   954
ML {*
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   955
  datatype tree = Text of string | Elem of string * tree list;
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   956
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   957
  fun slow_content (Text txt) = txt
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   958
    | slow_content (Elem (name, ts)) =
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   959
        "<" ^ name ^ ">" ^
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   960
        implode (map slow_content ts) ^
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   961
        "</" ^ name ^ ">"
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   962
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   963
  fun add_content (Text txt) = Buffer.add txt
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   964
    | add_content (Elem (name, ts)) =
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   965
        Buffer.add ("<" ^ name ^ ">") #>
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   966
        fold add_content ts #>
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   967
        Buffer.add ("</" ^ name ^ ">");
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   968
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   969
  fun fast_content tree =
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   970
    Buffer.empty |> add_content tree |> Buffer.content;
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   971
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   972
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   973
text {* The slowness of @{ML slow_content} is due to the @{ML implode} of
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   974
  the recursive results, because it copies previously produced strings
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   975
  again and again.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   976
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   977
  The incremental @{ML add_content} avoids this by operating on a
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
   978
  buffer that is passed through in a linear fashion.  Using @{ML_text
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   979
  "#>"} and contraction over the actual buffer argument saves some
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   980
  additional boiler-plate.  Of course, the two @{ML "Buffer.add"}
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   981
  invocations with concatenated strings could have been split into
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   982
  smaller parts, but this would have obfuscated the source without
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   983
  making a big difference in performance.  Here we have done some
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   984
  peephole-optimization for the sake of readability.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   985
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   986
  Another benefit of @{ML add_content} is its ``open'' form as a
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   987
  function on buffers that can be continued in further linear
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   988
  transformations, folding etc.  Thus it is more compositional than
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   989
  the naive @{ML slow_content}.  As realistic example, compare the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   990
  old-style @{ML "Term.maxidx_of_term: term -> int"} with the newer
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   991
  @{ML "Term.maxidx_term: term -> int -> int"} in Isabelle/Pure.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   992
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   993
  Note that @{ML fast_content} above is only defined as example.  In
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   994
  many practical situations, it is customary to provide the
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
   995
  incremental @{ML add_content} only and leave the initialization and
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
   996
  termination to the concrete application to the user.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   997
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   998
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
   999
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1000
section {* Message output channels \label{sec:message-channels} *}
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1001
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1002
text {* Isabelle provides output channels for different kinds of
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1003
  messages: regular output, high-volume tracing information, warnings,
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1004
  and errors.
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1005
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1006
  Depending on the user interface involved, these messages may appear
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1007
  in different text styles or colours.  The standard output for
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1008
  batch sessions prefixes each line of warnings by @{verbatim
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1009
  "###"} and errors by @{verbatim "***"}, but leaves anything else
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1010
  unchanged.  The message body may contain further markup and formatting,
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1011
  which is routinely used in the Prover IDE \cite{isabelle-jedit}.
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1012
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1013
  Messages are associated with the transaction context of the running
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1014
  Isar command.  This enables the front-end to manage commands and
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1015
  resulting messages together.  For example, after deleting a command
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1016
  from a given theory document version, the corresponding message
39872
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1017
  output can be retracted from the display.
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1018
*}
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1019
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1020
text %mlref {*
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1021
  \begin{mldecls}
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1022
  @{index_ML writeln: "string -> unit"} \\
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1023
  @{index_ML tracing: "string -> unit"} \\
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1024
  @{index_ML warning: "string -> unit"} \\
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1025
  @{index_ML error: "string -> 'a"} % FIXME Output.error_message (!?) \\
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1026
  \end{mldecls}
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1027
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1028
  \begin{description}
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1029
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1030
  \item @{ML writeln}~@{text "text"} outputs @{text "text"} as regular
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1031
  message.  This is the primary message output operation of Isabelle
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1032
  and should be used by default.
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1033
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1034
  \item @{ML tracing}~@{text "text"} outputs @{text "text"} as special
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1035
  tracing message, indicating potential high-volume output to the
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1036
  front-end (hundreds or thousands of messages issued by a single
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1037
  command).  The idea is to allow the user-interface to downgrade the
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1038
  quality of message display to achieve higher throughput.
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1039
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1040
  Note that the user might have to take special actions to see tracing
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1041
  output, e.g.\ switch to a different output window.  So this channel
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1042
  should not be used for regular output.
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1043
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1044
  \item @{ML warning}~@{text "text"} outputs @{text "text"} as
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1045
  warning, which typically means some extra emphasis on the front-end
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1046
  side (color highlighting, icons, etc.).
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1047
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1048
  \item @{ML error}~@{text "text"} raises exception @{ML ERROR}~@{text
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1049
  "text"} and thus lets the Isar toplevel print @{text "text"} on the
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1050
  error channel, which typically means some extra emphasis on the
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1051
  front-end side (color highlighting, icons, etc.).
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1052
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1053
  This assumes that the exception is not handled before the command
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1054
  terminates.  Handling exception @{ML ERROR}~@{text "text"} is a
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1055
  perfectly legal alternative: it means that the error is absorbed
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1056
  without any message output.
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1057
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1058
  \begin{warn}
54387
890e983cb07b tuned signature;
wenzelm
parents: 53982
diff changeset
  1059
  The actual error channel is accessed via @{ML Output.error_message}, but
51058
98c48d023136 some updates concerning Proof General;
wenzelm
parents: 48985
diff changeset
  1060
  the old interaction protocol of Proof~General \emph{crashes} if that
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1061
  function is used in regular ML code: error output and toplevel
52416
wenzelm
parents: 51636
diff changeset
  1062
  command failure always need to coincide in classic TTY interaction.
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1063
  \end{warn}
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1064
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1065
  \end{description}
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1066
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1067
  \begin{warn}
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1068
  Regular Isabelle/ML code should output messages exclusively by the
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1069
  official channels.  Using raw I/O on \emph{stdout} or \emph{stderr}
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1070
  instead (e.g.\ via @{ML TextIO.output}) is apt to cause problems in
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1071
  the presence of parallel and asynchronous processing of Isabelle
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1072
  theories.  Such raw output might be displayed by the front-end in
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1073
  some system console log, with a low chance that the user will ever
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1074
  see it.  Moreover, as a genuine side-effect on global process
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1075
  channels, there is no proper way to retract output when Isar command
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1076
  transactions are reset by the system.
39861
b8d89db3e238 use continental paragraph style, which works better with mixture of (in)formal text;
wenzelm
parents: 39859
diff changeset
  1077
  \end{warn}
39872
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1078
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1079
  \begin{warn}
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1080
  The message channels should be used in a message-oriented manner.
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1081
  This means that multi-line output that logically belongs together is
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1082
  issued by a single invocation of @{ML writeln} etc.\ with the
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1083
  functional concatenation of all message constituents.
39872
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1084
  \end{warn}
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1085
*}
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1086
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1087
text %mlex {* The following example demonstrates a multi-line
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1088
  warning.  Note that in some situations the user sees only the first
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1089
  line, so the most important point should be made first.
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1090
*}
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1091
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1092
ML_command {*
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1093
  warning (cat_lines
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1094
   ["Beware the Jabberwock, my son!",
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1095
    "The jaws that bite, the claws that catch!",
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1096
    "Beware the Jubjub Bird, and shun",
2b88d00d6790 more on messages;
wenzelm
parents: 39871
diff changeset
  1097
    "The frumious Bandersnatch!"]);
39835
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1098
*}
6cefd96bb71d modernized version of "Message output channels";
wenzelm
parents: 39830
diff changeset
  1099
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1100
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1101
section {* Exceptions \label{sec:exceptions} *}
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1102
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1103
text {* The Standard ML semantics of strict functional evaluation
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1104
  together with exceptions is rather well defined, but some delicate
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1105
  points need to be observed to avoid that ML programs go wrong
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1106
  despite static type-checking.  Exceptions in Isabelle/ML are
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1107
  subsequently categorized as follows.
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1108
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1109
  \paragraph{Regular user errors.}  These are meant to provide
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1110
  informative feedback about malformed input etc.
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1111
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1112
  The \emph{error} function raises the corresponding @{ML ERROR}
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1113
  exception, with a plain text message as argument.  @{ML ERROR}
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1114
  exceptions can be handled internally, in order to be ignored, turned
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1115
  into other exceptions, or cascaded by appending messages.  If the
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1116
  corresponding Isabelle/Isar command terminates with an @{ML ERROR}
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1117
  exception state, the system will print the result on the error
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1118
  channel (see \secref{sec:message-channels}).
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1119
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1120
  It is considered bad style to refer to internal function names or
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1121
  values in ML source notation in user error messages.  Do not use
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1122
  @{text "@{make_string}"} here!
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1123
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1124
  Grammatical correctness of error messages can be improved by
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1125
  \emph{omitting} final punctuation: messages are often concatenated
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1126
  or put into a larger context (e.g.\ augmented with source position).
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1127
  Note that punctuation after formal entities (types, terms, theorems) is
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1128
  particularly prone to user confusion.
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1129
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1130
  \paragraph{Program failures.}  There is a handful of standard
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1131
  exceptions that indicate general failure situations, or failures of
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1132
  core operations on logical entities (types, terms, theorems,
39856
wenzelm
parents: 39855
diff changeset
  1133
  theories, see \chref{ch:logic}).
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1134
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1135
  These exceptions indicate a genuine breakdown of the program, so the
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1136
  main purpose is to determine quickly what has happened where.
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1137
  Traditionally, the (short) exception message would include the name
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1138
  of an ML function, although this is no longer necessary, because the
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1139
  ML runtime system attaches detailed source position stemming from the
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
  1140
  corresponding @{ML_text raise} keyword.
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1141
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1142
  \medskip User modules can always introduce their own custom
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1143
  exceptions locally, e.g.\ to organize internal failures robustly
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1144
  without overlapping with existing exceptions.  Exceptions that are
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1145
  exposed in module signatures require extra care, though, and should
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1146
  \emph{not} be introduced by default.  Surprise by users of a module
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1147
  can be often minimized by using plain user errors instead.
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1148
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1149
  \paragraph{Interrupts.}  These indicate arbitrary system events:
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1150
  both the ML runtime system and the Isabelle/ML infrastructure signal
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1151
  various exceptional situations by raising the special
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1152
  @{ML Exn.Interrupt} exception in user code.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1153
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1154
  This is the one and only way that physical events can intrude an Isabelle/ML
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1155
  program. Such an interrupt can mean out-of-memory, stack overflow, timeout,
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1156
  internal signaling of threads, or a POSIX process signal. An Isabelle/ML
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1157
  program that intercepts interrupts becomes dependent on physical effects of
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1158
  the environment. Even worse, exception handling patterns that are too
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1159
  general by accident, e.g.\ by misspelled exception constructors, will cover
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1160
  interrupts unintentionally and thus render the program semantics
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1161
  ill-defined.
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1162
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1163
  Note that the Interrupt exception dates back to the original SML90
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1164
  language definition.  It was excluded from the SML97 version to
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1165
  avoid its malign impact on ML program semantics, but without
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1166
  providing a viable alternative.  Isabelle/ML recovers physical
40229
wenzelm
parents: 40153
diff changeset
  1167
  interruptibility (which is an indispensable tool to implement
wenzelm
parents: 40153
diff changeset
  1168
  managed evaluation of command transactions), but requires user code
wenzelm
parents: 40153
diff changeset
  1169
  to be strictly transparent wrt.\ interrupts.
39854
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1170
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1171
  \begin{warn}
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1172
  Isabelle/ML user code needs to terminate promptly on interruption,
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1173
  without guessing at its meaning to the system infrastructure.
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1174
  Temporary handling of interrupts for cleanup of global resources
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1175
  etc.\ needs to be followed immediately by re-raising of the original
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1176
  exception.
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1177
  \end{warn}
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1178
*}
7480a7a159cb more on "Exceptions";
wenzelm
parents: 39851
diff changeset
  1179
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1180
text %mlref {*
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1181
  \begin{mldecls}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1182
  @{index_ML try: "('a -> 'b) -> 'a -> 'b option"} \\
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1183
  @{index_ML can: "('a -> 'b) -> 'a -> bool"} \\
55838
e120a15b0ee6 more antiquotations;
wenzelm
parents: 55837
diff changeset
  1184
  @{index_ML_exception ERROR: string} \\
e120a15b0ee6 more antiquotations;
wenzelm
parents: 55837
diff changeset
  1185
  @{index_ML_exception Fail: string} \\
39856
wenzelm
parents: 39855
diff changeset
  1186
  @{index_ML Exn.is_interrupt: "exn -> bool"} \\
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1187
  @{index_ML reraise: "exn -> 'a"} \\
56303
4cc3f4db3447 clarified Isabelle/ML bootstrap, such that Execution does not require ML_Compiler;
wenzelm
parents: 56199
diff changeset
  1188
  @{index_ML Runtime.exn_trace: "(unit -> 'a) -> 'a"} \\
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1189
  \end{mldecls}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1190
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1191
  \begin{description}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1192
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1193
  \item @{ML try}~@{text "f x"} makes the partiality of evaluating
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1194
  @{text "f x"} explicit via the option datatype.  Interrupts are
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1195
  \emph{not} handled here, i.e.\ this form serves as safe replacement
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
  1196
  for the \emph{unsafe} version @{ML_text "(SOME"}~@{text "f
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
  1197
  x"}~@{ML_text "handle _ => NONE)"} that is occasionally seen in
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1198
  books about SML97, but not in Isabelle/ML.
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1199
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1200
  \item @{ML can} is similar to @{ML try} with more abstract result.
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1201
39856
wenzelm
parents: 39855
diff changeset
  1202
  \item @{ML ERROR}~@{text "msg"} represents user errors; this
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1203
  exception is normally raised indirectly via the @{ML error} function
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1204
  (see \secref{sec:message-channels}).
39856
wenzelm
parents: 39855
diff changeset
  1205
wenzelm
parents: 39855
diff changeset
  1206
  \item @{ML Fail}~@{text "msg"} represents general program failures.
wenzelm
parents: 39855
diff changeset
  1207
wenzelm
parents: 39855
diff changeset
  1208
  \item @{ML Exn.is_interrupt} identifies interrupts robustly, without
wenzelm
parents: 39855
diff changeset
  1209
  mentioning concrete exception constructors in user code.  Handled
wenzelm
parents: 39855
diff changeset
  1210
  interrupts need to be re-raised promptly!
wenzelm
parents: 39855
diff changeset
  1211
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1212
  \item @{ML reraise}~@{text "exn"} raises exception @{text "exn"}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1213
  while preserving its implicit position information (if possible,
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1214
  depending on the ML platform).
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1215
56303
4cc3f4db3447 clarified Isabelle/ML bootstrap, such that Execution does not require ML_Compiler;
wenzelm
parents: 56199
diff changeset
  1216
  \item @{ML Runtime.exn_trace}~@{ML_text "(fn () =>"}~@{text
40149
4c35be108990 proper markup of uninterpreted ML text as @{ML_text}, not @{verbatim};
wenzelm
parents: 40126
diff changeset
  1217
  "e"}@{ML_text ")"} evaluates expression @{text "e"} while printing
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1218
  a full trace of its stack of nested exceptions (if possible,
53739
599d8c324477 repaired latex (cf. 84522727f9d3);
wenzelm
parents: 53709
diff changeset
  1219
  depending on the ML platform).
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1220
56303
4cc3f4db3447 clarified Isabelle/ML bootstrap, such that Execution does not require ML_Compiler;
wenzelm
parents: 56199
diff changeset
  1221
  Inserting @{ML Runtime.exn_trace} into ML code temporarily is
53709
84522727f9d3 improved printing of exception trace in Poly/ML 5.5.1;
wenzelm
parents: 53167
diff changeset
  1222
  useful for debugging, but not suitable for production code.
39855
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1223
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1224
  \end{description}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1225
*}
d4299b415879 more on "Exceptions";
wenzelm
parents: 39854
diff changeset
  1226
39866
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1227
text %mlantiq {*
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1228
  \begin{matharray}{rcl}
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1229
  @{ML_antiquotation_def "assert"} & : & @{text ML_antiquotation} \\
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1230
  \end{matharray}
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1231
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1232
  \begin{description}
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1233
40110
93e7935d4cb5 added ML antiquotation @{assert};
wenzelm
parents: 39883
diff changeset
  1234
  \item @{text "@{assert}"} inlines a function
93e7935d4cb5 added ML antiquotation @{assert};
wenzelm
parents: 39883
diff changeset
  1235
  @{ML_type "bool -> unit"} that raises @{ML Fail} if the argument is
93e7935d4cb5 added ML antiquotation @{assert};
wenzelm
parents: 39883
diff changeset
  1236
  @{ML false}.  Due to inlining the source position of failed
93e7935d4cb5 added ML antiquotation @{assert};
wenzelm
parents: 39883
diff changeset
  1237
  assertions is included in the error output.
39866
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1238
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1239
  \end{description}
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1240
*}
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1241
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1242
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1243
section {* Strings of symbols \label{sec:symbols} *}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1244
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1245
text {* A \emph{symbol} constitutes the smallest textual unit in
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1246
  Isabelle/ML --- raw ML characters are normally not encountered at
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1247
  all.  Isabelle strings consist of a sequence of symbols, represented
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1248
  as a packed string or an exploded list of strings.  Each symbol is
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1249
  in itself a small string, which has either one of the following
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1250
  forms:
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1251
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1252
  \begin{enumerate}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1253
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1254
  \item a single ASCII character ``@{text "c"}'', for example
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1255
  ``\verb,a,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1256
56579
4c94f631c595 tuned spelling;
wenzelm
parents: 56420
diff changeset
  1257
  \item a codepoint according to UTF-8 (non-ASCII byte sequence),
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1258
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1259
  \item a regular symbol ``\verb,\,\verb,<,@{text "ident"}\verb,>,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1260
  for example ``\verb,\,\verb,<alpha>,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1261
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1262
  \item a control symbol ``\verb,\,\verb,<^,@{text "ident"}\verb,>,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1263
  for example ``\verb,\,\verb,<^bold>,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1264
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1265
  \item a raw symbol ``\verb,\,\verb,<^raw:,@{text text}\verb,>,''
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1266
  where @{text text} consists of printable characters excluding
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1267
  ``\verb,.,'' and ``\verb,>,'', for example
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1268
  ``\verb,\,\verb,<^raw:$\sum_{i = 1}^n$>,'',
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1269
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1270
  \item a numbered raw control symbol ``\verb,\,\verb,<^raw,@{text
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1271
  n}\verb,>, where @{text n} consists of digits, for example
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1272
  ``\verb,\,\verb,<^raw42>,''.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1273
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1274
  \end{enumerate}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1275
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1276
  The @{text "ident"} syntax for symbol names is @{text "letter
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1277
  (letter | digit)\<^sup>*"}, where @{text "letter = A..Za..z"} and @{text
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1278
  "digit = 0..9"}.  There are infinitely many regular symbols and
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1279
  control symbols, but a fixed collection of standard symbols is
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1280
  treated specifically.  For example, ``\verb,\,\verb,<alpha>,'' is
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1281
  classified as a letter, which means it may occur within regular
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1282
  Isabelle identifiers.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1283
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1284
  The character set underlying Isabelle symbols is 7-bit ASCII, but 8-bit
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1285
  character sequences are passed-through unchanged. Unicode/UCS data in UTF-8
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1286
  encoding is processed in a non-strict fashion, such that well-formed code
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1287
  sequences are recognized accordingly. Unicode provides its own collection of
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1288
  mathematical symbols, but within the core Isabelle/ML world there is no link
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1289
  to the standard collection of Isabelle regular symbols.
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1290
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1291
  \medskip Output of Isabelle symbols depends on the print mode. For example,
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1292
  the standard {\LaTeX} setup of the Isabelle document preparation system
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1293
  would present ``\verb,\,\verb,<alpha>,'' as @{text "\<alpha>"}, and
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1294
  ``\verb,\,\verb,<^bold>,\verb,\,\verb,<alpha>,'' as @{text "\<^bold>\<alpha>"}. On-screen
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1295
  rendering usually works by mapping a finite subset of Isabelle symbols to
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1296
  suitable Unicode characters.
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1297
*}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1298
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1299
text %mlref {*
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1300
  \begin{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1301
  @{index_ML_type "Symbol.symbol": string} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1302
  @{index_ML Symbol.explode: "string -> Symbol.symbol list"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1303
  @{index_ML Symbol.is_letter: "Symbol.symbol -> bool"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1304
  @{index_ML Symbol.is_digit: "Symbol.symbol -> bool"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1305
  @{index_ML Symbol.is_quasi: "Symbol.symbol -> bool"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1306
  @{index_ML Symbol.is_blank: "Symbol.symbol -> bool"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1307
  \end{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1308
  \begin{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1309
  @{index_ML_type "Symbol.sym"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1310
  @{index_ML Symbol.decode: "Symbol.symbol -> Symbol.sym"} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1311
  \end{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1312
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1313
  \begin{description}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1314
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1315
  \item Type @{ML_type "Symbol.symbol"} represents individual Isabelle
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1316
  symbols.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1317
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1318
  \item @{ML "Symbol.explode"}~@{text "str"} produces a symbol list
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1319
  from the packed form.  This function supersedes @{ML
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1320
  "String.explode"} for virtually all purposes of manipulating text in
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1321
  Isabelle!\footnote{The runtime overhead for exploded strings is
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1322
  mainly that of the list structure: individual symbols that happen to
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1323
  be a singleton string do not require extra memory in Poly/ML.}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1324
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1325
  \item @{ML "Symbol.is_letter"}, @{ML "Symbol.is_digit"}, @{ML
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1326
  "Symbol.is_quasi"}, @{ML "Symbol.is_blank"} classify standard
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1327
  symbols according to fixed syntactic conventions of Isabelle, cf.\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1328
  \cite{isabelle-isar-ref}.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1329
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1330
  \item Type @{ML_type "Symbol.sym"} is a concrete datatype that
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1331
  represents the different kinds of symbols explicitly, with
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1332
  constructors @{ML "Symbol.Char"}, @{ML "Symbol.UTF8"},
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1333
  @{ML "Symbol.Sym"}, @{ML "Symbol.Ctrl"}, @{ML "Symbol.Raw"},
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1334
  @{ML "Symbol.Malformed"}.
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1335
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1336
  \item @{ML "Symbol.decode"} converts the string representation of a
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1337
  symbol into the datatype version.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1338
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1339
  \end{description}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1340
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1341
  \paragraph{Historical note.} In the original SML90 standard the
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1342
  primitive ML type @{ML_type char} did not exists, and @{ML_text
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1343
  "explode: string -> string list"} produced a list of singleton
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1344
  strings like @{ML "raw_explode: string -> string list"} in
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1345
  Isabelle/ML today.  When SML97 came out, Isabelle did not adopt its
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1346
  somewhat anachronistic 8-bit or 16-bit characters, but the idea of
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1347
  exploding a string into a list of small strings was extended to
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1348
  ``symbols'' as explained above.  Thus Isabelle sources can refer to
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1349
  an infinite store of user-defined symbols, without having to worry
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1350
  about the multitude of Unicode encodings that have emerged over the
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1351
  years.  *}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1352
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1353
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1354
section {* Basic data types *}
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1355
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1356
text {* The basis library proposal of SML97 needs to be treated with
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1357
  caution.  Many of its operations simply do not fit with important
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1358
  Isabelle/ML conventions (like ``canonical argument order'', see
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1359
  \secref{sec:canonical-argument-order}), others cause problems with
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1360
  the parallel evaluation model of Isabelle/ML (such as @{ML
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1361
  TextIO.print} or @{ML OS.Process.system}).
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1362
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1363
  Subsequently we give a brief overview of important operations on
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1364
  basic ML data types.
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1365
*}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1366
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1367
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1368
subsection {* Characters *}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1369
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1370
text %mlref {*
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1371
  \begin{mldecls}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1372
  @{index_ML_type char} \\
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1373
  \end{mldecls}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1374
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1375
  \begin{description}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1376
39864
wenzelm
parents: 39863
diff changeset
  1377
  \item Type @{ML_type char} is \emph{not} used.  The smallest textual
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1378
  unit in Isabelle is represented as a ``symbol'' (see
39864
wenzelm
parents: 39863
diff changeset
  1379
  \secref{sec:symbols}).
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1380
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1381
  \end{description}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1382
*}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1383
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1384
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1385
subsection {* Strings *}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1386
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1387
text %mlref {*
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1388
  \begin{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1389
  @{index_ML_type string} \\
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1390
  \end{mldecls}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1391
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1392
  \begin{description}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1393
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1394
  \item Type @{ML_type string} represents immutable vectors of 8-bit
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1395
  characters.  There are operations in SML to convert back and forth
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1396
  to actual byte vectors, which are seldom used.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1397
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1398
  This historically important raw text representation is used for
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1399
  Isabelle-specific purposes with the following implicit substructures
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1400
  packed into the string content:
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1401
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1402
  \begin{enumerate}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1403
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1404
  \item sequence of Isabelle symbols (see also \secref{sec:symbols}),
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1405
  with @{ML Symbol.explode} as key operation;
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1406
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1407
  \item XML tree structure via YXML (see also \cite{isabelle-sys}),
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1408
  with @{ML YXML.parse_body} as key operation.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1409
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1410
  \end{enumerate}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1411
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1412
  Note that Isabelle/ML string literals may refer Isabelle symbols
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1413
  like ``\verb,\,\verb,<alpha>,'' natively, \emph{without} escaping
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1414
  the backslash.  This is a consequence of Isabelle treating all
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1415
  source text as strings of symbols, instead of raw characters.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1416
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1417
  \end{description}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1418
*}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1419
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1420
text %mlex {* The subsequent example illustrates the difference of
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1421
  physical addressing of bytes versus logical addressing of symbols in
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1422
  Isabelle strings.
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1423
*}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1424
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1425
ML_val {*
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1426
  val s = "\<A>";
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1427
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1428
  @{assert} (length (Symbol.explode s) = 1);
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1429
  @{assert} (size s = 4);
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1430
*}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1431
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1432
text {* Note that in Unicode renderings of the symbol @{text "\<A>"},
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1433
  variations of encodings like UTF-8 or UTF-16 pose delicate questions
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1434
  about the multi-byte representations of its codepoint, which is outside
52421
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1435
  of the 16-bit address space of the original Unicode standard from
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1436
  the 1990-ies.  In Isabelle/ML it is just ``\verb,\,\verb,<A>,''
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1437
  literally, using plain ASCII characters beyond any doubts. *}
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1438
6d93140a206c clarified strings of symbols, including ML string literals;
wenzelm
parents: 52420
diff changeset
  1439
39862
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1440
subsection {* Integers *}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1441
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1442
text %mlref {*
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1443
  \begin{mldecls}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1444
  @{index_ML_type int} \\
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1445
  \end{mldecls}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1446
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1447
  \begin{description}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1448
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1449
  \item Type @{ML_type int} represents regular mathematical integers, which
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1450
  are \emph{unbounded}. Overflow is treated properly, but should never happen
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1451
  in practice.\footnote{The size limit for integer bit patterns in memory is
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1452
  64\,MB for 32-bit Poly/ML, and much higher for 64-bit systems.} This works
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1453
  uniformly for all supported ML platforms (Poly/ML and SML/NJ).
39862
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1454
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1455
  Literal integers in ML text are forced to be of this one true
52417
wenzelm
parents: 52416
diff changeset
  1456
  integer type --- adhoc overloading of SML97 is disabled.
39862
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1457
55837
154855d9a564 clarified names of antiquotations and markup;
wenzelm
parents: 55112
diff changeset
  1458
  Structure @{ML_structure IntInf} of SML97 is obsolete and superseded by
154855d9a564 clarified names of antiquotations and markup;
wenzelm
parents: 55112
diff changeset
  1459
  @{ML_structure Int}.  Structure @{ML_structure Integer} in @{file
39862
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1460
  "~~/src/Pure/General/integer.ML"} provides some additional
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1461
  operations.
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1462
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1463
  \end{description}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1464
*}
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1465
78e6ec83762a more on "Integers";
wenzelm
parents: 39861
diff changeset
  1466
40302
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1467
subsection {* Time *}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1468
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1469
text %mlref {*
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1470
  \begin{mldecls}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1471
  @{index_ML_type Time.time} \\
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1472
  @{index_ML seconds: "real -> Time.time"} \\
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1473
  \end{mldecls}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1474
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1475
  \begin{description}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1476
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1477
  \item Type @{ML_type Time.time} represents time abstractly according
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1478
  to the SML97 basis library definition.  This is adequate for
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1479
  internal ML operations, but awkward in concrete time specifications.
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1480
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1481
  \item @{ML seconds}~@{text "s"} turns the concrete scalar @{text
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1482
  "s"} (measured in seconds) into an abstract time value.  Floating
52417
wenzelm
parents: 52416
diff changeset
  1483
  point numbers are easy to use as configuration options in the
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1484
  context (see \secref{sec:config-options}) or system options that
52417
wenzelm
parents: 52416
diff changeset
  1485
  are maintained externally.
40302
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1486
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1487
  \end{description}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1488
*}
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1489
2a33038d858b more on "Time" in Isabelle/ML;
wenzelm
parents: 40229
diff changeset
  1490
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1491
subsection {* Options *}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1492
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1493
text %mlref {*
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1494
  \begin{mldecls}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1495
  @{index_ML Option.map: "('a -> 'b) -> 'a option -> 'b option"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1496
  @{index_ML is_some: "'a option -> bool"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1497
  @{index_ML is_none: "'a option -> bool"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1498
  @{index_ML the: "'a option -> 'a"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1499
  @{index_ML these: "'a list option -> 'a list"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1500
  @{index_ML the_list: "'a option -> 'a list"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1501
  @{index_ML the_default: "'a -> 'a option -> 'a"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1502
  \end{mldecls}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1503
*}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1504
52417
wenzelm
parents: 52416
diff changeset
  1505
text {* Apart from @{ML Option.map} most other operations defined in
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1506
  structure @{ML_structure Option} are alien to Isabelle/ML and never
52417
wenzelm
parents: 52416
diff changeset
  1507
  used.  The operations shown above are defined in @{file
wenzelm
parents: 52416
diff changeset
  1508
  "~~/src/Pure/General/basics.ML"}.  *}
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1509
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1510
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1511
subsection {* Lists *}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1512
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1513
text {* Lists are ubiquitous in ML as simple and light-weight
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1514
  ``collections'' for many everyday programming tasks.  Isabelle/ML
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1515
  provides important additions and improvements over operations that
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1516
  are predefined in the SML97 library. *}
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1517
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1518
text %mlref {*
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1519
  \begin{mldecls}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1520
  @{index_ML cons: "'a -> 'a list -> 'a list"} \\
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1521
  @{index_ML member: "('b * 'a -> bool) -> 'a list -> 'b -> bool"} \\
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1522
  @{index_ML insert: "('a * 'a -> bool) -> 'a -> 'a list -> 'a list"} \\
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1523
  @{index_ML remove: "('b * 'a -> bool) -> 'b -> 'a list -> 'a list"} \\
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1524
  @{index_ML update: "('a * 'a -> bool) -> 'a -> 'a list -> 'a list"} \\
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1525
  \end{mldecls}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1526
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1527
  \begin{description}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1528
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1529
  \item @{ML cons}~@{text "x xs"} evaluates to @{text "x :: xs"}.
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1530
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1531
  Tupled infix operators are a historical accident in Standard ML.
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1532
  The curried @{ML cons} amends this, but it should be only used when
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1533
  partial application is required.
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1534
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1535
  \item @{ML member}, @{ML insert}, @{ML remove}, @{ML update} treat
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1536
  lists as a set-like container that maintains the order of elements.
40800
330eb65c9469 Parse.liberal_name for document antiquotations and attributes;
wenzelm
parents: 40508
diff changeset
  1537
  See @{file "~~/src/Pure/library.ML"} for the full specifications
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1538
  (written in ML).  There are some further derived operations like
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1539
  @{ML union} or @{ML inter}.
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1540
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1541
  Note that @{ML insert} is conservative about elements that are
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1542
  already a @{ML member} of the list, while @{ML update} ensures that
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1543
  the latest entry is always put in front.  The latter discipline is
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1544
  often more appropriate in declarations of context data
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1545
  (\secref{sec:context-data}) that are issued by the user in Isar
52417
wenzelm
parents: 52416
diff changeset
  1546
  source: later declarations take precedence over earlier ones.
39874
bbac63bbcffe clarified "lists as a set-like container";
wenzelm
parents: 39872
diff changeset
  1547
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1548
  \end{description}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1549
*}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1550
52417
wenzelm
parents: 52416
diff changeset
  1551
text %mlex {* Using canonical @{ML fold} together with @{ML cons} (or
wenzelm
parents: 52416
diff changeset
  1552
  similar standard operations) alternates the orientation of data.
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1553
  The is quite natural and should not be altered forcible by inserting
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1554
  extra applications of @{ML rev}.  The alternative @{ML fold_rev} can
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1555
  be used in the few situations, where alternation should be
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1556
  prevented.
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1557
*}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1558
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1559
ML {*
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1560
  val items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1561
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1562
  val list1 = fold cons items [];
39866
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1563
  @{assert} (list1 = rev items);
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1564
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1565
  val list2 = fold_rev cons items [];
39866
5ec01d5acd0c more robust examples: explicit @{assert} instead of unchecked output;
wenzelm
parents: 39864
diff changeset
  1566
  @{assert} (list2 = items);
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1567
*}
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1568
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1569
text {* The subsequent example demonstrates how to \emph{merge} two
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1570
  lists in a natural way. *}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1571
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1572
ML {*
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1573
  fun merge_lists eq (xs, ys) = fold_rev (insert eq) ys xs;
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1574
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1575
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1576
text {* Here the first list is treated conservatively: only the new
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1577
  elements from the second list are inserted.  The inside-out order of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1578
  insertion via @{ML fold_rev} attempts to preserve the order of
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1579
  elements in the result.
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1580
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1581
  This way of merging lists is typical for context data
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1582
  (\secref{sec:context-data}).  See also @{ML merge} as defined in
40800
330eb65c9469 Parse.liberal_name for document antiquotations and attributes;
wenzelm
parents: 40508
diff changeset
  1583
  @{file "~~/src/Pure/library.ML"}.
39883
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1584
*}
3d3d6038bdaa more on "Canonical argument order";
wenzelm
parents: 39881
diff changeset
  1585
39863
c0de5386017e more on "Basic data types";
wenzelm
parents: 39862
diff changeset
  1586
39875
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1587
subsection {* Association lists *}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1588
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1589
text {* The operations for association lists interpret a concrete list
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1590
  of pairs as a finite function from keys to values.  Redundant
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1591
  representations with multiple occurrences of the same key are
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1592
  implicitly normalized: lookup and update only take the first
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1593
  occurrence into account.
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1594
*}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1595
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1596
text {*
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1597
  \begin{mldecls}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1598
  @{index_ML AList.lookup: "('a * 'b -> bool) -> ('b * 'c) list -> 'a -> 'c option"} \\
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1599
  @{index_ML AList.defined: "('a * 'b -> bool) -> ('b * 'c) list -> 'a -> bool"} \\
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1600
  @{index_ML AList.update: "('a * 'a -> bool) -> 'a * 'b -> ('a * 'b) list -> ('a * 'b) list"} \\
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1601
  \end{mldecls}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1602
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1603
  \begin{description}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1604
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1605
  \item @{ML AList.lookup}, @{ML AList.defined}, @{ML AList.update}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1606
  implement the main ``framework operations'' for mappings in
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1607
  Isabelle/ML, following standard conventions for their names and
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1608
  types.
39875
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1609
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1610
  Note that a function called @{verbatim lookup} is obliged to express its
39875
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1611
  partiality via an explicit option element.  There is no choice to
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1612
  raise an exception, without changing the name to something like
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1613
  @{text "the_element"} or @{text "get"}.
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1614
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1615
  The @{text "defined"} operation is essentially a contraction of @{ML
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1616
  is_some} and @{verbatim "lookup"}, but this is sufficiently frequent to
39875
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1617
  justify its independent existence.  This also gives the
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1618
  implementation some opportunity for peep-hole optimization.
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1619
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1620
  \end{description}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1621
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1622
  Association lists are adequate as simple implementation of finite mappings
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1623
  in many practical situations. A more advanced table structure is defined in
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1624
  @{file "~~/src/Pure/General/table.ML"}; that version scales easily to
39875
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1625
  thousands or millions of elements.
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1626
*}
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1627
648c930125f6 more on "Association lists", based on more succinct version of older material;
wenzelm
parents: 39874
diff changeset
  1628
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1629
subsection {* Unsynchronized references *}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1630
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1631
text %mlref {*
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1632
  \begin{mldecls}
39870
wenzelm
parents: 39868
diff changeset
  1633
  @{index_ML_type "'a Unsynchronized.ref"} \\
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1634
  @{index_ML Unsynchronized.ref: "'a -> 'a Unsynchronized.ref"} \\
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1635
  @{index_ML "!": "'a Unsynchronized.ref -> 'a"} \\
46262
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
  1636
  @{index_ML_op ":=": "'a Unsynchronized.ref * 'a -> unit"} \\
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1637
  \end{mldecls}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1638
*}
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1639
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1640
text {* Due to ubiquitous parallelism in Isabelle/ML (see also
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1641
  \secref{sec:multi-threading}), the mutable reference cells of
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1642
  Standard ML are notorious for causing problems.  In a highly
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1643
  parallel system, both correctness \emph{and} performance are easily
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1644
  degraded when using mutable data.
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1645
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1646
  The unwieldy name of @{ML Unsynchronized.ref} for the constructor
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1647
  for references in Isabelle/ML emphasizes the inconveniences caused by
46262
912b42e64fde tuned ML infixes;
wenzelm
parents: 42665
diff changeset
  1648
  mutability.  Existing operations @{ML "!"}  and @{ML_op ":="} are
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1649
  unchanged, but should be used with special precautions, say in a
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1650
  strictly local situation that is guaranteed to be restricted to
40508
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1651
  sequential evaluation --- now and in the future.
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1652
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1653
  \begin{warn}
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1654
  Never @{ML_text "open Unsynchronized"}, not even in a local scope!
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1655
  Pretending that mutable state is no problem is a very bad idea.
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1656
  \end{warn}
76894f975440 never open Unsynchronized;
wenzelm
parents: 40310
diff changeset
  1657
*}
39859
381e16bb5f46 more on "Basic ML data types";
wenzelm
parents: 39856
diff changeset
  1658
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1659
39870
wenzelm
parents: 39868
diff changeset
  1660
section {* Thread-safe programming \label{sec:multi-threading} *}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1661
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1662
text {* Multi-threaded execution has become an everyday reality in
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1663
  Isabelle since Poly/ML 5.2.1 and Isabelle2008.  Isabelle/ML provides
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1664
  implicit and explicit parallelism by default, and there is no way
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1665
  for user-space tools to ``opt out''.  ML programs that are purely
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1666
  functional, output messages only via the official channels
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1667
  (\secref{sec:message-channels}), and do not intercept interrupts
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1668
  (\secref{sec:exceptions}) can participate in the multi-threaded
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1669
  environment immediately without further ado.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1670
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1671
  More ambitious tools with more fine-grained interaction with the
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1672
  environment need to observe the principles explained below.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1673
*}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1674
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1675
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1676
subsection {* Multi-threading with shared memory *}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1677
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1678
text {* Multiple threads help to organize advanced operations of the
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1679
  system, such as real-time conditions on command transactions,
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1680
  sub-components with explicit communication, general asynchronous
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1681
  interaction etc.  Moreover, parallel evaluation is a prerequisite to
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1682
  make adequate use of the CPU resources that are available on
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1683
  multi-core systems.\footnote{Multi-core computing does not mean that
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1684
  there are ``spare cycles'' to be wasted.  It means that the
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1685
  continued exponential speedup of CPU performance due to ``Moore's
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1686
  Law'' follows different rules: clock frequency has reached its peak
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1687
  around 2005, and applications need to be parallelized in order to
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1688
  avoid a perceived loss of performance.  See also
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1689
  \cite{Sutter:2005}.}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1690
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1691
  Isabelle/Isar exploits the inherent structure of theories and proofs to
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1692
  support \emph{implicit parallelism} to a large extent. LCF-style theorem
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1693
  proving provides almost ideal conditions for that, see also
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1694
  \cite{Wenzel:2009}. This means, significant parts of theory and proof
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1695
  checking is parallelized by default. In Isabelle2013, a maximum
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1696
  speedup-factor of 3.5 on 4 cores and 6.5 on 8 cores can be expected
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1697
  \cite{Wenzel:2013:ITP}.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1698
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1699
  \medskip ML threads lack the memory protection of separate
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1700
  processes, and operate concurrently on shared heap memory.  This has
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1701
  the advantage that results of independent computations are directly
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1702
  available to other threads: abstract values can be passed without
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1703
  copying or awkward serialization that is typically required for
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1704
  separate processes.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1705
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1706
  To make shared-memory multi-threading work robustly and efficiently,
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1707
  some programming guidelines need to be observed.  While the ML
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1708
  system is responsible to maintain basic integrity of the
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1709
  representation of ML values in memory, the application programmer
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1710
  needs to ensure that multi-threaded execution does not break the
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1711
  intended semantics.
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1712
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1713
  \begin{warn}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1714
  To participate in implicit parallelism, tools need to be
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1715
  thread-safe.  A single ill-behaved tool can affect the stability and
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1716
  performance of the whole system.
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1717
  \end{warn}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1718
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1719
  Apart from observing the principles of thread-safeness passively, advanced
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1720
  tools may also exploit parallelism actively, e.g.\ by using library
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1721
  functions for parallel list operations (\secref{sec:parlist}).
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1722
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1723
  \begin{warn}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1724
  Parallel computing resources are managed centrally by the
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1725
  Isabelle/ML infrastructure.  User programs must not fork their own
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1726
  ML threads to perform heavy computations.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1727
  \end{warn}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1728
*}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1729
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1730
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1731
subsection {* Critical shared resources *}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1732
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1733
text {* Thread-safeness is mainly concerned about concurrent
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1734
  read/write access to shared resources, which are outside the purely
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1735
  functional world of ML.  This covers the following in particular.
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1736
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1737
  \begin{itemize}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1738
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1739
  \item Global references (or arrays), i.e.\ mutable memory cells that
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1740
  persist over several invocations of associated
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1741
  operations.\footnote{This is independent of the visibility of such
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1742
  mutable values in the toplevel scope.}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1743
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1744
  \item Global state of the running Isabelle/ML process, i.e.\ raw I/O
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1745
  channels, environment variables, current working directory.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1746
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1747
  \item Writable resources in the file-system that are shared among
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1748
  different threads or external processes.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1749
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1750
  \end{itemize}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1751
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1752
  Isabelle/ML provides various mechanisms to avoid critical shared
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1753
  resources in most situations.  As last resort there are some
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1754
  mechanisms for explicit synchronization.  The following guidelines
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1755
  help to make Isabelle/ML programs work smoothly in a concurrent
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1756
  environment.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1757
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1758
  \begin{itemize}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1759
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1760
  \item Avoid global references altogether.  Isabelle/Isar maintains a
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1761
  uniform context that incorporates arbitrary data declared by user
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1762
  programs (\secref{sec:context-data}).  This context is passed as
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1763
  plain value and user tools can get/map their own data in a purely
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1764
  functional manner.  Configuration options within the context
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1765
  (\secref{sec:config-options}) provide simple drop-in replacements
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1766
  for historic reference variables.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1767
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1768
  \item Keep components with local state information re-entrant.
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1769
  Instead of poking initial values into (private) global references, a
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1770
  new state record can be created on each invocation, and passed
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1771
  through any auxiliary functions of the component.  The state record
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1772
  may well contain mutable references, without requiring any special
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1773
  synchronizations, as long as each invocation gets its own copy, and the
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1774
  tool itself is single-threaded.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1775
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1776
  \item Avoid raw output on @{text "stdout"} or @{text "stderr"}.  The
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1777
  Poly/ML library is thread-safe for each individual output operation,
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1778
  but the ordering of parallel invocations is arbitrary.  This means
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1779
  raw output will appear on some system console with unpredictable
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1780
  interleaving of atomic chunks.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1781
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1782
  Note that this does not affect regular message output channels
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1783
  (\secref{sec:message-channels}).  An official message id is associated
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1784
  with the command transaction from where it originates, independently
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1785
  of other transactions.  This means each running Isar command has
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1786
  effectively its own set of message channels, and interleaving can
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1787
  only happen when commands use parallelism internally (and only at
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1788
  message boundaries).
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1789
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1790
  \item Treat environment variables and the current working directory
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  1791
  of the running process as read-only.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1792
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1793
  \item Restrict writing to the file-system to unique temporary files.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1794
  Isabelle already provides a temporary directory that is unique for
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1795
  the running process, and there is a centralized source of unique
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1796
  serial numbers in Isabelle/ML.  Thus temporary files that are passed
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1797
  to to some external process will be always disjoint, and thus
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1798
  thread-safe.
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1799
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1800
  \end{itemize}
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1801
*}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1802
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1803
text %mlref {*
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1804
  \begin{mldecls}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1805
  @{index_ML File.tmp_path: "Path.T -> Path.T"} \\
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1806
  @{index_ML serial_string: "unit -> string"} \\
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1807
  \end{mldecls}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1808
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1809
  \begin{description}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1810
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1811
  \item @{ML File.tmp_path}~@{text "path"} relocates the base
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1812
  component of @{text "path"} into the unique temporary directory of
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1813
  the running Isabelle/ML process.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1814
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1815
  \item @{ML serial_string}~@{text "()"} creates a new serial number
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1816
  that is unique over the runtime of the Isabelle/ML process.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1817
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1818
  \end{description}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1819
*}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1820
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1821
text %mlex {* The following example shows how to create unique
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1822
  temporary file names.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1823
*}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1824
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1825
ML {*
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1826
  val tmp1 = File.tmp_path (Path.basic ("foo" ^ serial_string ()));
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1827
  val tmp2 = File.tmp_path (Path.basic ("foo" ^ serial_string ()));
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1828
  @{assert} (tmp1 <> tmp2);
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1829
*}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1830
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1831
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1832
subsection {* Explicit synchronization *}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1833
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1834
text {* Isabelle/ML also provides some explicit synchronization
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1835
  mechanisms, for the rare situations where mutable shared resources
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1836
  are really required.  These are based on the synchronizations
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1837
  primitives of Poly/ML, which have been adapted to the specific
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1838
  assumptions of the concurrent Isabelle/ML environment.  User code
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1839
  must not use the Poly/ML primitives directly!
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1840
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1841
  \medskip The most basic synchronization concept is a single
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1842
  \emph{critical section} (also called ``monitor'' in the literature).
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1843
  A thread that enters the critical section prevents all other threads
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1844
  from doing the same.  A thread that is already within the critical
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1845
  section may re-enter it in an idempotent manner.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1846
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1847
  Such centralized locking is convenient, because it prevents
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1848
  deadlocks by construction.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1849
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1850
  \medskip More fine-grained locking works via \emph{synchronized
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1851
  variables}.  An explicit state component is associated with
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1852
  mechanisms for locking and signaling.  There are operations to
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1853
  await a condition, change the state, and signal the change to all
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1854
  other waiting threads.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1855
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1856
  Here the synchronized access to the state variable is \emph{not}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1857
  re-entrant: direct or indirect nesting within the same thread will
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1858
  cause a deadlock!
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1859
*}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1860
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1861
text %mlref {*
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1862
  \begin{mldecls}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1863
  @{index_ML NAMED_CRITICAL: "string -> (unit -> 'a) -> 'a"} \\
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1864
  @{index_ML CRITICAL: "(unit -> 'a) -> 'a"} \\
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1865
  \end{mldecls}
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1866
  \begin{mldecls}
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1867
  @{index_ML_type "'a Synchronized.var"} \\
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1868
  @{index_ML Synchronized.var: "string -> 'a -> 'a Synchronized.var"} \\
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1869
  @{index_ML Synchronized.guarded_access: "'a Synchronized.var ->
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1870
  ('a -> ('b * 'a) option) -> 'b"} \\
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1871
  \end{mldecls}
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1872
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1873
  \begin{description}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1874
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1875
  \item @{ML NAMED_CRITICAL}~@{text "name e"} evaluates @{text "e ()"}
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1876
  within the central critical section of Isabelle/ML.  No other thread
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1877
  may do so at the same time, but non-critical parallel execution will
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1878
  continue.  The @{text "name"} argument is used for tracing and might
39868
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1879
  help to spot sources of congestion.
732ab20fec3b misc tuning;
wenzelm
parents: 39867
diff changeset
  1880
52418
f00e4d8dde4c updated to Isabelle2013;
wenzelm
parents: 52417
diff changeset
  1881
  Entering the critical section without contention is very fast.  Each
f00e4d8dde4c updated to Isabelle2013;
wenzelm
parents: 52417
diff changeset
  1882
  thread should stay within the critical section only very briefly,
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1883
  otherwise parallel performance may degrade.
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1884
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1885
  \item @{ML CRITICAL} is the same as @{ML NAMED_CRITICAL} with empty
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1886
  name argument.
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1887
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1888
  \item Type @{ML_type "'a Synchronized.var"} represents synchronized
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1889
  variables with state of type @{ML_type 'a}.
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1890
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1891
  \item @{ML Synchronized.var}~@{text "name x"} creates a synchronized
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1892
  variable that is initialized with value @{text "x"}.  The @{text
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1893
  "name"} is used for tracing.
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1894
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1895
  \item @{ML Synchronized.guarded_access}~@{text "var f"} lets the
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1896
  function @{text "f"} operate within a critical section on the state
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1897
  @{text "x"} as follows: if @{text "f x"} produces @{ML NONE}, it
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1898
  continues to wait on the internal condition variable, expecting that
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1899
  some other thread will eventually change the content in a suitable
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1900
  manner; if @{text "f x"} produces @{ML SOME}~@{text "(y, x')"} it is
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1901
  satisfied and assigns the new state value @{text "x'"}, broadcasts a
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1902
  signal to all waiting threads on the associated condition variable,
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1903
  and returns the result @{text "y"}.
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1904
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1905
  \end{description}
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1906
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1907
  There are some further variants of the @{ML
40800
330eb65c9469 Parse.liberal_name for document antiquotations and attributes;
wenzelm
parents: 40508
diff changeset
  1908
  Synchronized.guarded_access} combinator, see @{file
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1909
  "~~/src/Pure/Concurrent/synchronized.ML"} for details.
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1910
*}
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1911
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1912
text %mlex {* The following example implements a counter that produces
39871
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1913
  positive integers that are unique over the runtime of the Isabelle
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1914
  process:
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1915
*}
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1916
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1917
ML {*
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1918
  local
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1919
    val counter = Synchronized.var "counter" 0;
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1920
  in
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1921
    fun next () =
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1922
      Synchronized.guarded_access counter
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1923
        (fn i =>
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1924
          let val j = i + 1
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1925
          in SOME (j, j) end);
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1926
  end;
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1927
*}
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1928
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1929
ML {*
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1930
  val a = next ();
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1931
  val b = next ();
b905971407a1 more on synchronized variables;
wenzelm
parents: 39870
diff changeset
  1932
  @{assert} (a <> b);
39867
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1933
*}
a8363532cd4d somewhat modernized version of "Thread-safe programming";
wenzelm
parents: 39866
diff changeset
  1934
40800
330eb65c9469 Parse.liberal_name for document antiquotations and attributes;
wenzelm
parents: 40508
diff changeset
  1935
text {* \medskip See @{file "~~/src/Pure/Concurrent/mailbox.ML"} how
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1936
  to implement a mailbox as synchronized variable over a purely
57417
29fe9bac501b more tight Mailbox: single list is sufficient for single receiver, reverse outside critical section;
wenzelm
parents: 57350
diff changeset
  1937
  functional list. *}
40126
916cb4a28ffd misc tuning;
wenzelm
parents: 40110
diff changeset
  1938
52419
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1939
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1940
section {* Managed evaluation *}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1941
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1942
text {* Execution of Standard ML follows the model of strict
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1943
  functional evaluation with optional exceptions.  Evaluation happens
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1944
  whenever some function is applied to (sufficiently many)
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1945
  arguments. The result is either an explicit value or an implicit
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1946
  exception.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1947
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1948
  \emph{Managed evaluation} in Isabelle/ML organizes expressions and
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1949
  results to control certain physical side-conditions, to say more
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1950
  specifically when and how evaluation happens.  For example, the
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1951
  Isabelle/ML library supports lazy evaluation with memoing, parallel
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1952
  evaluation via futures, asynchronous evaluation via promises,
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1953
  evaluation with time limit etc.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1954
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1955
  \medskip An \emph{unevaluated expression} is represented either as
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1956
  unit abstraction @{verbatim "fn () => a"} of type
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1957
  @{verbatim "unit -> 'a"} or as regular function
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1958
  @{verbatim "fn a => b"} of type @{verbatim "'a -> 'b"}.  Both forms
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1959
  occur routinely, and special care is required to tell them apart ---
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1960
  the static type-system of SML is only of limited help here.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1961
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1962
  The first form is more intuitive: some combinator @{text "(unit ->
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1963
  'a) -> 'a"} applies the given function to @{text "()"} to initiate
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1964
  the postponed evaluation process.  The second form is more flexible:
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1965
  some combinator @{text "('a -> 'b) -> 'a -> 'b"} acts like a
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1966
  modified form of function application; several such combinators may
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1967
  be cascaded to modify a given function, before it is ultimately
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1968
  applied to some argument.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1969
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1970
  \medskip \emph{Reified results} make the disjoint sum of regular
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1971
  values versions exceptional situations explicit as ML datatype:
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1972
  @{text "'a result = Res of 'a | Exn of exn"}.  This is typically
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1973
  used for administrative purposes, to store the overall outcome of an
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1974
  evaluation process.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1975
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1976
  \emph{Parallel exceptions} aggregate reified results, such that
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1977
  multiple exceptions are digested as a collection in canonical form
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1978
  that identifies exceptions according to their original occurrence.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1979
  This is particular important for parallel evaluation via futures
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1980
  \secref{sec:futures}, which are organized as acyclic graph of
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1981
  evaluations that depend on other evaluations: exceptions stemming
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1982
  from shared sub-graphs are exposed exactly once and in the order of
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1983
  their original occurrence (e.g.\ when printed at the toplevel).
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1984
  Interrupt counts as neutral element here: it is treated as minimal
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1985
  information about some canceled evaluation process, and is absorbed
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1986
  by the presence of regular program exceptions.  *}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1987
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1988
text %mlref {*
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1989
  \begin{mldecls}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1990
  @{index_ML_type "'a Exn.result"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1991
  @{index_ML Exn.capture: "('a -> 'b) -> 'a -> 'b Exn.result"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1992
  @{index_ML Exn.interruptible_capture: "('a -> 'b) -> 'a -> 'b Exn.result"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1993
  @{index_ML Exn.release: "'a Exn.result -> 'a"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1994
  @{index_ML Par_Exn.release_all: "'a Exn.result list -> 'a list"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1995
  @{index_ML Par_Exn.release_first: "'a Exn.result list -> 'a list"} \\
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1996
  \end{mldecls}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1997
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1998
  \begin{description}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  1999
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2000
  \item Type @{ML_type "'a Exn.result"} represents the disjoint sum of
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2001
  ML results explicitly, with constructor @{ML Exn.Res} for regular
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2002
  values and @{ML "Exn.Exn"} for exceptions.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2003
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2004
  \item @{ML Exn.capture}~@{text "f x"} manages the evaluation of
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2005
  @{text "f x"} such that exceptions are made explicit as @{ML
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2006
  "Exn.Exn"}.  Note that this includes physical interrupts (see also
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2007
  \secref{sec:exceptions}), so the same precautions apply to user
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2008
  code: interrupts must not be absorbed accidentally!
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2009
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2010
  \item @{ML Exn.interruptible_capture} is similar to @{ML
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2011
  Exn.capture}, but interrupts are immediately re-raised as required
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2012
  for user code.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2013
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2014
  \item @{ML Exn.release}~@{text "result"} releases the original
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2015
  runtime result, exposing its regular value or raising the reified
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2016
  exception.
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2017
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2018
  \item @{ML Par_Exn.release_all}~@{text "results"} combines results
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2019
  that were produced independently (e.g.\ by parallel evaluation).  If
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2020
  all results are regular values, that list is returned.  Otherwise,
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2021
  the collection of all exceptions is raised, wrapped-up as collective
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2022
  parallel exception.  Note that the latter prevents access to
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  2023
  individual exceptions by conventional @{verbatim "handle"} of ML.
52419
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2024
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2025
  \item @{ML Par_Exn.release_first} is similar to @{ML
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2026
  Par_Exn.release_all}, but only the first exception that has occurred
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2027
  in the original evaluation process is raised again, the others are
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2028
  ignored.  That single exception may get handled by conventional
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  2029
  means in ML.
52419
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2030
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2031
  \end{description}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2032
*}
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2033
24018d1167a3 more on managed evaluation;
wenzelm
parents: 52418
diff changeset
  2034
52420
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2035
subsection {* Parallel skeletons \label{sec:parlist} *}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2036
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2037
text {*
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2038
  Algorithmic skeletons are combinators that operate on lists in
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2039
  parallel, in the manner of well-known @{text map}, @{text exists},
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2040
  @{text forall} etc.  Management of futures (\secref{sec:futures})
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2041
  and their results as reified exceptions is wrapped up into simple
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2042
  programming interfaces that resemble the sequential versions.
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2043
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2044
  What remains is the application-specific problem to present
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2045
  expressions with suitable \emph{granularity}: each list element
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2046
  corresponds to one evaluation task.  If the granularity is too
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2047
  coarse, the available CPUs are not saturated.  If it is too
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2048
  fine-grained, CPU cycles are wasted due to the overhead of
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2049
  organizing parallel processing.  In the worst case, parallel
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2050
  performance will be less than the sequential counterpart!
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2051
*}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2052
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2053
text %mlref {*
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2054
  \begin{mldecls}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2055
  @{index_ML Par_List.map: "('a -> 'b) -> 'a list -> 'b list"} \\
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2056
  @{index_ML Par_List.get_some: "('a -> 'b option) -> 'a list -> 'b option"} \\
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2057
  \end{mldecls}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2058
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2059
  \begin{description}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2060
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2061
  \item @{ML Par_List.map}~@{text "f [x\<^sub>1, \<dots>, x\<^sub>n]"} is like @{ML
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2062
  "map"}~@{text "f [x\<^sub>1, \<dots>, x\<^sub>n]"}, but the evaluation of @{text "f x\<^sub>i"}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2063
  for @{text "i = 1, \<dots>, n"} is performed in parallel.
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2064
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2065
  An exception in any @{text "f x\<^sub>i"} cancels the overall evaluation
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2066
  process.  The final result is produced via @{ML
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2067
  Par_Exn.release_first} as explained above, which means the first
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2068
  program exception that happened to occur in the parallel evaluation
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2069
  is propagated, and all other failures are ignored.
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2070
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2071
  \item @{ML Par_List.get_some}~@{text "f [x\<^sub>1, \<dots>, x\<^sub>n]"} produces some
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2072
  @{text "f x\<^sub>i"} that is of the form @{text "SOME y\<^sub>i"}, if that
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2073
  exists, otherwise @{text "NONE"}.  Thus it is similar to @{ML
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2074
  Library.get_first}, but subject to a non-deterministic parallel
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2075
  choice process.  The first successful result cancels the overall
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2076
  evaluation process; other exceptions are propagated as for @{ML
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2077
  Par_List.map}.
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2078
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2079
  This generic parallel choice combinator is the basis for derived
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2080
  forms, such as @{ML Par_List.find_some}, @{ML Par_List.exists}, @{ML
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2081
  Par_List.forall}.
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2082
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2083
  \end{description}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2084
*}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2085
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2086
text %mlex {* Subsequently, the Ackermann function is evaluated in
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2087
  parallel for some ranges of arguments. *}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2088
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2089
ML_val {*
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2090
  fun ackermann 0 n = n + 1
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2091
    | ackermann m 0 = ackermann (m - 1) 1
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2092
    | ackermann m n = ackermann (m - 1) (ackermann m (n - 1));
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2093
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2094
  Par_List.map (ackermann 2) (500 upto 1000);
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2095
  Par_List.map (ackermann 3) (5 upto 10);
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2096
*}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2097
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2098
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2099
subsection {* Lazy evaluation *}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2100
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2101
text {*
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2102
  Classic lazy evaluation works via the @{text lazy}~/ @{text force} pair of
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2103
  operations: @{text lazy} to wrap an unevaluated expression, and @{text
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2104
  force} to evaluate it once and store its result persistently. Later
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2105
  invocations of @{text force} retrieve the stored result without another
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2106
  evaluation. Isabelle/ML refines this idea to accommodate the aspects of
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2107
  multi-threading, synchronous program exceptions and asynchronous interrupts.
57347
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2108
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2109
  The first thread that invokes @{text force} on an unfinished lazy value
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2110
  changes its state into a \emph{promise} of the eventual result and starts
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2111
  evaluating it. Any other threads that @{text force} the same lazy value in
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2112
  the meantime need to wait for it to finish, by producing a regular result or
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2113
  program exception. If the evaluation attempt is interrupted, this event is
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2114
  propagated to all waiting threads and the lazy value is reset to its
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2115
  original state.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2116
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2117
  This means a lazy value is completely evaluated at most once, in a
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2118
  thread-safe manner. There might be multiple interrupted evaluation attempts,
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2119
  and multiple receivers of intermediate interrupt events. Interrupts are
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2120
  \emph{not} made persistent: later evaluation attempts start again from the
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2121
  original expression.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2122
*}
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2123
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2124
text %mlref {*
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2125
  \begin{mldecls}
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2126
  @{index_ML_type "'a lazy"} \\
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2127
  @{index_ML Lazy.lazy: "(unit -> 'a) -> 'a lazy"} \\
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2128
  @{index_ML Lazy.value: "'a -> 'a lazy"} \\
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2129
  @{index_ML Lazy.force: "'a lazy -> 'a"} \\
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2130
  \end{mldecls}
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2131
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2132
  \begin{description}
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2133
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2134
  \item Type @{ML_type "'a lazy"} represents lazy values over type @{verbatim
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2135
  "'a"}.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2136
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2137
  \item @{ML Lazy.lazy}~@{text "(fn () => e)"} wraps the unevaluated
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2138
  expression @{text e} as unfinished lazy value.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2139
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2140
  \item @{ML Lazy.value}~@{text a} wraps the value @{text a} as finished lazy
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2141
  value.  When forced, it returns @{text a} without any further evaluation.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2142
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2143
  There is very low overhead for this proforma wrapping of strict values as
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2144
  lazy values.
57347
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2145
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2146
  \item @{ML Lazy.force}~@{text x} produces the result of the lazy value in a
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2147
  thread-safe manner as explained above. Thus it may cause the current thread
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2148
  to wait on a pending evaluation attempt by another thread.
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2149
5c8f4a35d8d7 more on "Lazy evaluation";
wenzelm
parents: 56594
diff changeset
  2150
  \end{description}
52420
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2151
*}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2152
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2153
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2154
subsection {* Futures \label{sec:futures} *}
52420
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2155
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2156
text {*
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2157
  Futures help to organize parallel execution in a value-oriented manner, with
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2158
  @{text fork}~/ @{text join} as the main pair of operations, and some further
57350
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2159
  variants; see also \cite{Wenzel:2009,Wenzel:2013:ITP}. Unlike lazy values,
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2160
  futures are evaluated strictly and spontaneously on separate worker threads.
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2161
  Futures may be canceled, which leads to interrupts on running evaluation
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2162
  attempts, and forces structurally related futures to fail for all time;
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2163
  already finished futures remain unchanged. Exceptions between related
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2164
  futures are propagated as well, and turned into parallel exceptions (see
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2165
  above).
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2166
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2167
  Technically, a future is a single-assignment variable together with a
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2168
  \emph{task} that serves administrative purposes, notably within the
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2169
  \emph{task queue} where new futures are registered for eventual evaluation
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2170
  and the worker threads retrieve their work.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2171
57350
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2172
  The pool of worker threads is limited, in correlation with the number of
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2173
  physical cores on the machine. Note that allocation of runtime resources may
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2174
  be distorted either if workers yield CPU time (e.g.\ via system sleep or
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2175
  wait operations), or if non-worker threads contend for significant runtime
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2176
  resources independently. There is a limited number of replacement worker
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2177
  threads that get activated in certain explicit wait conditions, after a
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2178
  timeout.
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2179
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2180
  \medskip Each future task belongs to some \emph{task group}, which
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2181
  represents the hierarchic structure of related tasks, together with the
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2182
  exception status a that point. By default, the task group of a newly created
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2183
  future is a new sub-group of the presently running one, but it is also
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2184
  possible to indicate different group layouts under program control.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2185
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2186
  Cancellation of futures actually refers to the corresponding task group and
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2187
  all its sub-groups. Thus interrupts are propagated down the group hierarchy.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2188
  Regular program exceptions are treated likewise: failure of the evaluation
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2189
  of some future task affects its own group and all sub-groups. Given a
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2190
  particular task group, its \emph{group status} cumulates all relevant
57350
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2191
  exceptions according to its position within the group hierarchy. Interrupted
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2192
  tasks that lack regular result information, will pick up parallel exceptions
fc4d65afdf13 more on "Futures";
wenzelm
parents: 57349
diff changeset
  2193
  from the cumulative group status.
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2194
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2195
  \medskip A \emph{passive future} or \emph{promise} is a future with slightly
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2196
  different evaluation policies: there is only a single-assignment variable
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2197
  and some expression to evaluate for the \emph{failed} case (e.g.\ to clean
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2198
  up resources when canceled). A regular result is produced by external means,
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2199
  using a separate \emph{fulfill} operation.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2200
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2201
  Promises are managed in the same task queue, so regular futures may depend
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2202
  on them. This allows a form of reactive programming, where some promises are
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2203
  used as minimal elements (or guards) within the future dependency graph:
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2204
  when these promises are fulfilled the evaluation of subsequent futures
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2205
  starts spontaneously, according to their own inter-dependencies.
52420
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2206
*}
81d5072935ac more on managed evaluation;
wenzelm
parents: 52419
diff changeset
  2207
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2208
text %mlref {*
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2209
  \begin{mldecls}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2210
  @{index_ML_type "'a future"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2211
  @{index_ML Future.fork: "(unit -> 'a) -> 'a future"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2212
  @{index_ML Future.forks: "Future.params -> (unit -> 'a) list -> 'a future list"} \\
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2213
  @{index_ML Future.join: "'a future -> 'a"} \\
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2214
  @{index_ML Future.joins: "'a future list -> 'a list"} \\
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2215
  @{index_ML Future.value: "'a -> 'a future"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2216
  @{index_ML Future.map: "('a -> 'b) -> 'a future -> 'b future"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2217
  @{index_ML Future.cancel: "'a future -> unit"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2218
  @{index_ML Future.cancel_group: "Future.group -> unit"} \\[0.5ex]
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2219
  @{index_ML Future.promise: "(unit -> unit) -> 'a future"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2220
  @{index_ML Future.fulfill: "'a future -> 'a -> unit"} \\
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2221
  \end{mldecls}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2222
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2223
  \begin{description}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2224
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2225
  \item Type @{ML_type "'a future"} represents future values over type
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2226
  @{verbatim "'a"}.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2227
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2228
  \item @{ML Future.fork}~@{text "(fn () => e)"} registers the unevaluated
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2229
  expression @{text e} as unfinished future value, to be evaluated eventually
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2230
  on the parallel worker-thread farm. This is a shorthand for @{ML
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2231
  Future.forks} below, with default parameters and a single expression.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2232
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2233
  \item @{ML Future.forks}~@{text "params exprs"} is the general interface to
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2234
  fork several futures simultaneously. The @{text params} consist of the
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2235
  following fields:
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2236
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2237
  \begin{itemize}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2238
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2239
  \item @{text "name : string"} (default @{ML "\"\""}) specifies a common name
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2240
  for the tasks of the forked futures, which serves diagnostic purposes.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2241
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2242
  \item @{text "group : Future.group option"} (default @{ML NONE}) specifies
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2243
  an optional task group for the forked futures. @{ML NONE} means that a new
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2244
  sub-group of the current worker-thread task context is created. If this is
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2245
  not a worker thread, the group will be a new root in the group hierarchy.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2246
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2247
  \item @{text "deps : Future.task list"} (default @{ML "[]"}) specifies
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2248
  dependencies on other future tasks, i.e.\ the adjacency relation in the
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2249
  global task queue. Dependencies on already finished tasks are ignored.
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2250
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2251
  \item @{text "pri : int"} (default @{ML 0}) specifies a priority within the
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2252
  task queue.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2253
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2254
  Typically there is only little deviation from the default priority @{ML 0}.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2255
  As a rule of thumb, @{ML "~1"} means ``low priority" and @{ML 1} means
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2256
  ``high priority''.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2257
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2258
  Note that the task priority only affects the position in the queue, not the
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2259
  thread priority. When a worker thread picks up a task for processing, it
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2260
  runs with the normal thread priority to the end (or until canceled). Higher
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2261
  priority tasks that are queued later need to wait until this (or another)
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2262
  worker thread becomes free again.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2263
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2264
  \item @{text "interrupts : bool"} (default @{ML true}) tells whether the
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2265
  worker thread that processes the corresponding task is initially put into
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2266
  interruptible state. This state may change again while running, by modifying
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2267
  the thread attributes.
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2268
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2269
  With interrupts disabled, a running future task cannot be canceled.  It is
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2270
  the responsibility of the programmer that this special state is retained
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2271
  only briefly.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2272
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2273
  \end{itemize}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2274
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2275
  \item @{ML Future.join}~@{text x} retrieves the value of an already finished
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2276
  future, which may lead to an exception, according to the result of its
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2277
  previous evaluation.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2278
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2279
  For an unfinished future there are several cases depending on the role of
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2280
  the current thread and the status of the future. A non-worker thread waits
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2281
  passively until the future is eventually evaluated. A worker thread
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2282
  temporarily changes its task context and takes over the responsibility to
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2283
  evaluate the future expression on the spot. The latter is done in a
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2284
  thread-safe manner: other threads that intend to join the same future need
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2285
  to wait until the ongoing evaluation is finished.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2286
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2287
  Note that excessive use of dynamic dependencies of futures by adhoc joining
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2288
  may lead to bad utilization of CPU cores, due to threads waiting on other
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2289
  threads to finish required futures. The future task farm has a limited
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2290
  amount of replacement threads that continue working on unrelated tasks after
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2291
  some timeout.
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2292
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2293
  Whenever possible, static dependencies of futures should be specified
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2294
  explicitly when forked (see @{text deps} above). Thus the evaluation can
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2295
  work from the bottom up, without join conflicts and wait states.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2296
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2297
  \item @{ML Future.joins}~@{text xs} joins the given list of futures
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2298
  simultaneously, which is more efficient than @{ML "map Future.join"}~@{text
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2299
  xs}.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2300
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2301
  Based on the dependency graph of tasks, the current thread takes over the
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2302
  responsibility to evaluate future expressions that are required for the main
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2303
  result, working from the bottom up. Waiting on future results that are
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2304
  presently evaluated on other threads only happens as last resort, when no
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2305
  other unfinished futures are left over.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2306
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2307
  \item @{ML Future.value}~@{text a} wraps the value @{text a} as finished
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2308
  future value, bypassing the worker-thread farm. When joined, it returns
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2309
  @{text a} without any further evaluation.
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2310
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2311
  There is very low overhead for this proforma wrapping of strict values as
57421
94081154306d misc tuning;
wenzelm
parents: 57417
diff changeset
  2312
  futures.
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2313
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2314
  \item @{ML Future.map}~@{text "f x"} is a fast-path implementation of @{ML
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2315
  Future.fork}~@{text "(fn () => f ("}@{ML Future.join}~@{text "x))"}, which
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2316
  avoids the full overhead of the task queue and worker-thread farm as far as
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2317
  possible. The function @{text f} is supposed to be some trivial
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2318
  post-processing or projection of the future result.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2319
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2320
  \item @{ML Future.cancel}~@{text "x"} cancels the task group of the given
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2321
  future, using @{ML Future.cancel_group} below.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2322
57349
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2323
  \item @{ML Future.cancel_group}~@{text "group"} cancels all tasks of the
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2324
  given task group for all time. Threads that are presently processing a task
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2325
  of the given group are interrupted: it may take some time until they are
4817154180d6 more on "Futures";
wenzelm
parents: 57348
diff changeset
  2326
  actually terminated. Tasks that are queued but not yet processed are
57348
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2327
  dequeued and forced into interrupted state. Since the task group is itself
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2328
  invalidated, any further attempt to fork a future that belongs to it will
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2329
  yield a canceled result as well.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2330
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2331
  \item @{ML Future.promise}~@{text abort} registers a passive future with the
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2332
  given @{text abort} operation: it is invoked when the future task group is
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2333
  canceled.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2334
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2335
  \item @{ML Future.fulfill}~@{text "x a"} finishes the passive future @{text
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2336
  x} by the given value @{text a}. If the promise has already been canceled,
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2337
  the attempt to fulfill it causes an exception.
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2338
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2339
  \end{description}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2340
*}
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2341
a6b1847b6335 more on "Future values";
wenzelm
parents: 57347
diff changeset
  2342
47180
c14fda8fee38 improving spelling
bulwahn
parents: 46262
diff changeset
  2343
end