Contents
Part I An introduction to OCaml
Chapter 1 The core language
1.1 Basics
1.2 Data types
1.3 Functions as values
1.4 Records and variants
1.4.1 Record and variant disambiguation
1.5 Imperative features
1.6 Exceptions
1.7 Lazy expressions
1.8 Symbolic processing of expressions
1.9 Pretty-printing
1.10 Printf formats
1.11 Standalone OCaml programs
Chapter 2 The module system
2.1 Structures
2.2 Signatures
2.3 Functors
2.4 Functors and type abstraction
2.5 Modules and separate compilation
Chapter 3 Objects in OCaml
3.1 Classes and objects
3.2 Immediate objects
3.3 Reference to self
3.4 Initializers
3.5 Virtual methods
3.6 Private methods
3.7 Class interfaces
3.8 Inheritance
3.9 Multiple inheritance
3.10 Parameterized classes
3.11 Polymorphic methods
3.12 Using coercions
3.13 Functional objects
3.14 Cloning objects
3.15 Recursive classes
3.16 Binary methods
3.17 Friends
Chapter 4 Labeled arguments
4.1 Optional arguments
4.2 Labels and type inference
4.3 Suggestions for labeling
Chapter 5 Polymorphic variants
5.1 Basic use
5.2 Advanced use
5.3 Weaknesses of polymorphic variants
Chapter 6 Polymorphism and its limitations
6.1 Weak polymorphism and mutation
6.1.1 Weakly polymorphic types
6.1.2 The value restriction
6.1.3 The relaxed value restriction
6.1.4 Variance and value restriction
6.1.5 Abstract data types
6.2 Polymorphic recursion
6.2.1 Explicitly polymorphic annotations
6.2.2 More examples
6.3 Higher-rank polymorphic functions
Chapter 7 Generalized algebraic datatypes
7.1 Recursive functions
7.2 Type inference
7.3 Refutation cases
7.4 Advanced examples
7.5 Existential type names in error messages
7.6 Explicit naming of existentials
7.7 Equations on non-local abstract types
7.8 Types used as GADT indices
7.8.1 Legacy behavior: types in the current module
Chapter 8 Advanced examples with classes and modules
8.1 Extended example: bank accounts
8.2 Simple modules as classes
8.2.1 Strings
8.2.2 Hashtbl
8.2.3 Sets
8.3 The subject/observer pattern
Chapter 9 Parallel programming
9.1 Domains
9.1.1 Joining domains
9.2 Domainslib: A library for nested-parallel programming
9.2.1 Parallelising Fibonacci using domainslib
9.2.2 Parallel iteration constructs
9.3 Parallel garbage collection
9.4 Memory model: The easy bits
9.5 Blocking synchronisation
9.5.1 Interaction with systhreads
9.6 Interaction with C bindings
9.7 Atomics
9.7.1 Lock-free stack
9.7.2 Atomic record fields
Chapter 10 Memory model: The hard bits
10.1 Why weakly consistent memory?
10.1.1 Compiler optimisations
10.1.2 Hardware optimisations
10.2 Data race freedom implies sequential consistency
10.2.1 Memory locations
10.2.2 Happens-before relation
10.2.3 Data race
10.2.4 DRF-SC
10.3 Reasoning with DRF-SC
10.4 Local data race freedom
10.5 An operational view of the memory model
10.5.1 Non-atomic locations
10.5.2 Domains
10.5.3 Non-atomic accesses
10.5.4 Atomic accesses
10.5.5 Reasoning with the semantics
10.6 Non-compliant operations
Part II The OCaml language
Chapter 11 The OCaml language
11.1 Lexical conventions
11.2 Values
11.2.1 Base values
11.2.2 Tuples
11.2.3 Records
11.2.4 Arrays
11.2.5 Variant values
11.2.6 Polymorphic variants
11.2.7 Functions
11.2.8 Objects
11.3 Names
11.4 Type expressions
11.5 Constants
11.6 Patterns
11.7 Expressions
11.7.1 Precedence and associativity
11.7.2 Basic expressions
11.7.3 Control structures
11.7.4 Operations on data structures
11.7.5 Operators
11.7.6 Objects
11.7.7 Coercions
11.7.8 Local structure items
11.7.9 Other
11.8 Type and exception definitions
11.8.1 Type definitions
11.8.2 Exception definitions
11.9 Classes
11.9.1 Class types
11.9.2 Class expressions
11.9.3 Class definitions
11.9.4 Class specifications
11.9.5 Class type definitions
11.10 Module types (module specifications)
11.10.1 Simple module types
11.10.2 Signatures
11.10.3 Functor types
11.10.4 The
with
operator
11.11 Module expressions (module implementations)
11.11.1 Simple module expressions
11.11.2 Structures
11.11.3 Functors
11.12 Compilation units
Chapter 12 Language extensions
12.1 Recursive definitions of values
12.2 Recursive modules
12.3 Private types
12.3.1 Private variant and record types
12.3.2 Private type abbreviations
12.3.3 Private row types
12.4 Locally abstract types
12.5 Module-dependent functions and first-class modules
12.5.1 Introduction
12.5.2 Reference
12.6 Recovering the type of a module
12.7 Substituting inside a signature
12.7.1 Destructive substitutions
12.7.2 Local substitution declarations
12.7.3 Module type substitutions
12.8 Type-level module aliases
12.9 Overriding in open statements
12.10 Generalized algebraic datatypes
12.11 Syntax for Bigarray access
12.12 Attributes
12.12.1 Built-in attributes
12.13 Extension nodes
12.13.1 Built-in extension nodes
12.14 Extensible variant types
12.14.1 Private extensible variant types
12.15 Generative functors
12.16 Extension-only syntax
12.16.1 Extension operators
12.16.2 Extension literals
12.17 Inline records
12.18 Documentation comments
12.18.1 Floating comments
12.18.2 Item comments
12.18.3 Label comments
12.19 Extended indexing operators
12.19.1 Multi-index notation
12.20 Empty variant types
12.21 Alerts
12.21.1 Marking a component
12.21.2 Controlling which alerts are enabled
12.21.3 Shorthand syntax for deprecation
12.22 Generalized open statements
12.23 Binding operators
12.23.1 Examples
12.23.2 Conventions
12.23.3 General desugaring rules
12.23.4 Short notation for variable bindings (let-punning)
12.24 Effect handlers
12.24.1 Basics
12.24.2 Concurrency
12.24.3 User-level threads
12.24.4 Control inversion
12.24.5 Semantics
12.24.6 Shallow handlers
12.25 Type-directed disambiguation of array literals
12.26 Labeled tuples
12.27 External types
Part III The OCaml tools
Chapter 13 Batch compilation (ocamlc)
13.1 Overview of the compiler
13.2 Options
13.3 Modules and the file system
13.4 Common errors
13.5 Warning reference
13.5.1 Warning 6: Label omitted in function application
13.5.2 Warning 9: missing fields in a record pattern
13.5.3 Warning 52: fragile constant pattern
13.5.4 Warning 57: Ambiguous or-pattern variables under guard
13.5.5 Warning 74: Pattern matching degraded to partial.
Chapter 14 The toplevel system or REPL (ocaml)
14.1 Options
14.2 Toplevel directives
14.3 The toplevel and the module system
14.4 Common errors
14.5 Building custom toplevel systems:
ocamlmktop
14.5.1 Options
14.6 The native toplevel:
ocamlnat
(experimental)
Chapter 15 The runtime system (ocamlrun)
15.1 Overview
15.2 Options
15.3 Dynamic loading of shared libraries
15.4 Common errors
Chapter 16 Native-code compilation (ocamlopt)
16.1 Overview of the compiler
16.2 Options
16.3 Common errors
16.4 Running executables produced by ocamlopt
16.5 Compatibility with the bytecode compiler
Chapter 17 Lexer and parser generators (ocamllex, ocamlyacc)
17.1 Overview of
ocamllex
17.1.1 Options
17.2 Syntax of lexer definitions
17.2.1 Header and trailer
17.2.2 Naming regular expressions
17.2.3 Entry points
17.2.4 Regular expressions
17.2.5 Actions
17.2.6 Variables in regular expressions
17.2.7 Refill handlers
17.2.8 Reserved identifiers
17.3 Overview of
ocamlyacc
17.4 Syntax of grammar definitions
17.4.1 Header and trailer
17.4.2 Declarations
17.4.3 Rules
17.4.4 Error handling
17.5 Options
17.6 A complete example
17.7 Common errors
Chapter 18 Dependency generator (ocamldep)
18.1 Options
18.2 A typical Makefile
Chapter 19 The documentation generator (ocamldoc)
19.1 Usage
19.1.1 Invocation
19.1.2 Merging of module information
19.1.3 Coding rules
19.2 Syntax of documentation comments
19.2.1 Placement of documentation comments
19.2.2 The Stop special comment
19.2.3 Syntax of documentation comments
19.2.4 Text formatting
19.2.5 Documentation tags (@-tags)
19.3 Custom generators
19.3.1 The generator modules
19.3.2 Handling custom tags
19.4 Adding command line options
19.4.1 Compilation and usage
Chapter 20 The debugger (ocamldebug)
20.1 Compiling for debugging
20.2 Invocation
20.2.1 Starting the debugger
20.2.2 Initialization file
20.2.3 Exiting the debugger
20.3 Commands
20.3.1 Getting help
20.3.2 Accessing the debugger state
20.4 Executing a program
20.4.1 Events
20.4.2 Starting the debugged program
20.4.3 Running the program
20.4.4 Time travel
20.4.5 Killing the program
20.5 Breakpoints
20.6 The call stack
20.7 Examining variable values
20.8 Controlling the debugger
20.8.1 Setting the program name and arguments
20.8.2 How programs are loaded
20.8.3 Search path for files
20.8.4 Working directory
20.8.5 Turning reverse execution on and off
20.8.6 Behavior of the debugger with respect to
fork
20.8.7 Stopping execution when new code is loaded
20.8.8 Communication between the debugger and the program
20.8.9 Fine-tuning the debugger
20.8.10 User-defined printers
20.9 Miscellaneous commands
20.10 Running the debugger under Emacs
Chapter 21 Native debugging (gdb, lldb)
21.1 Overview
21.1.1 DWARF
21.1.2 Name Mangling
21.1.3 Frame Pointers
21.2 Compiling for Debugging
21.3 Using GDB
21.3.1 GDB Commands
21.4 Using LLDB
21.4.1 LLDB Commands
Chapter 22 Profiling (ocamlprof, perf)
22.1 Profiling execution counts with ocamlprof
22.1.1 Compiling for profiling
22.1.2 Profiling an execution
22.1.3 Printing profiling information
22.2 Time profiling with Linux perf
22.2.1 Background
22.2.2 Compiling for Profiling
22.2.3 Profiling an Execution
22.2.4 Displaying profiling information
22.2.5 Conclusion
22.3 Time profiling with macOS Instruments
22.4 Glossary
Chapter 23 Interfacing C with OCaml
23.1 Overview and compilation information
23.1.1 Declaring primitives
23.1.2 Implementing primitives
23.1.3 Statically linking C code with OCaml code
23.1.4 Dynamically linking C code with OCaml code
23.1.5 Choosing between static linking and dynamic linking
23.1.6 Building standalone custom runtime systems
23.2 The
value
type
23.2.1 Integer values
23.2.2 Blocks
23.2.3 Pointers outside the heap
23.3 Representation of OCaml data types
23.3.1 Atomic types
23.3.2 Tuples and records
23.3.3 Arrays
23.3.4 Concrete data types
23.3.5 Objects
23.3.6 Polymorphic variants
23.4 Operations on values
23.4.1 Kind tests
23.4.2 Operations on integers
23.4.3 Accessing blocks
23.4.4 Allocating blocks
23.4.5 Raising exceptions
23.5 Living in harmony with the garbage collector
23.5.1 Simple interface
23.5.2 Low-level interface
23.5.3 Pending actions and asynchronous exceptions
23.6 A complete example
23.7 Advanced topic: callbacks from C to OCaml
23.7.1 Applying OCaml closures from C
23.7.2
caml_result
: resource cleanup on OCaml exceptions
23.7.3 Obtaining or registering OCaml closures for use in C functions
23.7.4 Registering OCaml exceptions for use in C functions
23.7.5 Main program in C
23.7.6 Embedding the OCaml code in the C code
23.8 Advanced example with callbacks
23.9 Advanced topic: custom blocks
23.9.1 The
struct custom_operations
23.9.2 Allocating custom blocks
23.9.3 Accessing custom blocks
23.9.4 Writing custom serialization and deserialization functions
23.9.5 Choosing identifiers
23.9.6 Finalized blocks
23.10 Advanced topic: Bigarrays and the OCaml-C interface
23.10.1 Include file
23.10.2 Accessing an OCaml bigarray from C or Fortran
23.10.3 Wrapping a C or Fortran array as an OCaml Bigarray
23.11 Advanced topic: cheaper C call
23.11.1 Passing unboxed values
23.11.2 Direct C call
23.11.3 Example: calling C library functions without indirection
23.12 Advanced topic: multithreading
23.12.1 Registering threads created from C
23.12.2 Parallel execution of long-running C code with systhreads
23.13 Advanced topic: interfacing with Windows Unicode APIs
23.14 Building mixed C/OCaml libraries:
ocamlmklib
23.15 Cautionary words: the internal runtime API
23.15.1 Internal variables and CAML_INTERNALS
23.15.2 OCaml version macros
Chapter 24 Optimisation with Flambda
24.1 Overview
24.2 Command-line flags
24.2.1 Specification of optimisation parameters by round
24.3 Inlining
24.3.1 Classic inlining heuristic
24.3.2 Overview of “Flambda” inlining heuristics
24.3.3 Handling of specific language constructs
24.3.4 Inlining reports
24.3.5 Assessment of inlining benefit
24.3.6 Control of speculation
24.4 Specialisation
24.4.1 Assessment of specialisation benefit
24.5 Default settings of parameters
24.5.1 Settings at -O2 optimisation level
24.5.2 Settings at -O3 optimisation level
24.6 Manual control of inlining and specialisation
24.7 Simplification
24.8 Other code motion transformations
24.8.1 Lifting of constants
24.8.2 Lifting of toplevel let bindings
24.9 Unboxing transformations
24.9.1 Unboxing of closure variables
24.9.2 Unboxing of specialised arguments
24.9.3 Unboxing of closures
24.10 Removal of unused code and values
24.10.1 Removal of redundant let expressions
24.10.2 Removal of redundant program constructs
24.10.3 Removal of unused arguments
24.10.4 Removal of unused closure variables
24.11 Other code transformations
24.11.1 Transformation of non-escaping references into mutable variables
24.11.2 Substitution of closure variables for specialised arguments
24.12 Treatment of effects
24.13 Compilation of statically-allocated modules
24.14 Inhibition of optimisation
24.15 Use of unsafe operations
24.16 Glossary
Chapter 25 Fuzzing with afl-fuzz
25.1 Overview
25.2 Generating instrumentation
25.2.1 Advanced options
25.3 Example
Chapter 26 Runtime tracing with runtime events
26.1 Overview
26.2 Architecture
26.2.1 Event sources
26.2.2 Events transport
26.3 Usage
26.3.1 With OCaml APIs
26.3.2 With tooling
26.4 Custom events
26.4.1 Overview
26.4.2 Tracing custom events: an example
Chapter 27 The “Tail Modulo Constructor” program transformation
27.1 Disambiguation
27.2 Danger: getting out of tail-mod-cons
27.3 Details on the transformation
27.4 Current limitations
Chapter 28 Runtime detection of data races with ThreadSanitizer
28.1 Overview and usage
28.2 Performance implications
28.3 False negatives and false positives
28.4 Runtime options
28.5 Guidelines for linking
28.6 Changes in the delivery of signals
Part IV The OCaml library
Chapter 29 The core library
29.1 Built-in types and predefined exceptions
29.2 Module
Stdlib
: the initially opened module
Chapter 30 The standard library
Chapter 31 The compiler front-end
Chapter 32 The unix library: Unix system calls
Chapter 33 The str library: regular expressions and string processing
Chapter 34 The runtime_events library
Chapter 35 The threads library
Chapter 36 The dynlink library: dynamic loading and linking of object files
Chapter 37 Recently removed or moved libraries (Graphics, Bigarray, Num, LablTk)
37.1 The Graphics Library
37.2 The Bigarray Library
37.3 The Num Library
37.4 The Labltk Library and OCamlBrowser
Part V Indexes
