Encoding Errors with Result

Options aren’t always a sufficiently expressive way to report errors. Specifically, when you encode an error as None, there’s nowhere to say anything about the nature of the error.

Result.t is meant to address this deficiency. The type is defined as follows: 

module Result : sig
   type ('a,'b) t = | Ok of 'a
                    | Error of 'b
end

A Result.t is essentially an option augmented with the ability to store other information in the error case. Like Some and None for options, the constructors Ok and Error are available at the toplevel. As such, we can write:

[ Ok 3; Error "abject failure"; Ok 4 ];;
>- : (int, string) result list = [Ok 3; Error "abject failure"; Ok 4]

without first opening the Result module.

Error and Or_error

Result.t gives you complete freedom to choose the type of value you use to represent errors, but it’s often useful to standardize on an error type. Among other things, this makes it easier to write utility functions to automate common error handling patterns.  

But which type to choose? Is it better to represent errors as strings? Some more structured representation like XML? Or something else entirely?

Base’s answer to this question is the Error.t type. You can, for example, construct one from a string.

Error.of_string "something went wrong";;
>- : Error.t = something went wrong

An Or_error.t is simply a Result.t with the error case specialized to the Error.t type. Here’s an example.

Error (Error.of_string "failed!");;
>- : ('a, Error.t) result = Error failed!

The Or_error module provides a bunch of useful operators for constructing errors. For example, Or_error.try_with can be used for catching exceptions from a computation.

let float_of_string s =
  Or_error.try_with (fun () -> Float.of_string s);;
>val float_of_string : string -> float Or_error.t = <fun>
float_of_string "3.34";;
>- : float Or_error.t = Base__.Result.Ok 3.34
float_of_string "a.bc";;
>- : float Or_error.t =
>Base__.Result.Error (Invalid_argument "Float.of_string a.bc")

Perhaps the most common way to create Error.ts is using s-expressions. An s-expression is a balanced parenthetical expression where the leaves of the expressions are strings. Here’s a simple example:  

(This (is an) (s expression))

S-expressions are supported by the Sexplib package that is distributed with Base and is the most common serialization format used in Base. Indeed, most types in Base come with built-in s-expression converters.  

Error.create "Unexpected character" 'c' Char.sexp_of_t;;
>- : Error.t = ("Unexpected character" c)

We’re not restricted to doing this kind of error reporting with built-in types. As we’ll discuss in more detail in Chapter 20, Data Serialization With S-Expressions, Sexplib comes with a syntax extension that can autogenerate sexp converters for specific types. We can enable it in the toplevel with a #require statement enabling ppx_jane, which is a package that pulls in multiple different syntax extensions, including ppx_sexp_value, the one we need here. (Because of technical issues with the toplevel, we can’t easily enable these syntax extensions individually.)        

#require "ppx_jane";;
Error.t_of_sexp
  [%sexp ("List is too long",[1;2;3] : string * int list)];;
>- : Error.t = ("List is too long" (1 2 3))

Error also supports operations for transforming errors. For example, it’s often useful to augment an error with information about the context of the error or to combine multiple errors together. Error.tag and Error.of_list fulfill these roles:   

Error.tag
  (Error.of_list [ Error.of_string "Your tires were slashed";
                   Error.of_string "Your windshield was smashed" ])
  ~tag:"over the weekend";;
>- : Error.t =
>("over the weekend" "Your tires were slashed" "Your windshield was smashed")

A very common way of generating errors is the %message syntax extension, which provides a compact syntax for providing a string describing the error, along with further values represented as s-expressions. Here’s an example.

let a = "foo" and b = ("foo",[3;4]);;
>val a : string = "foo"
>val b : string * int list = ("foo", [3; 4])
Or_error.error_s
  [%message "Something went wrong" (a:string) (b: string * int list)];;
>- : 'a Or_error.t =
>Base__.Result.Error ("Something went wrong" (a foo) (b (foo (3 4))))

This is the most common idiom for generating Error.t’s.

bind and Other Error Handling Idioms

As you write more error handling code in OCaml, you’ll discover that certain patterns start to emerge. A number of these common patterns have been codified by functions in modules like Option and Result. One particularly useful pattern is built around the function bind, which is both an ordinary function and an infix operator >>=. Here’s the definition of bind for options:  

let bind option ~f =
  match option with
  | None -> None
  | Some x -> f x;;
>val bind : 'a option -> f:('a -> 'b option) -> 'b option = <fun>

As you can see, bind None f returns None without calling f, and bind (Some x) ~f returns f x. bind can be used as a way of sequencing together error-producing functions so that the first one to produce an error terminates the computation. Here’s a rewrite of compute_bounds to use a nested series of binds:

let compute_bounds ~compare list =
  let sorted = List.sort ~compare list in
  Option.bind (List.hd sorted) ~f:(fun first ->
    Option.bind (List.last sorted) ~f:(fun last ->
      Some (first,last)));;
>val compute_bounds : compare:('a -> 'a -> int) -> 'a list -> ('a * 'a) option =
>  <fun>

The preceding code is a little bit hard to swallow, however, on a syntactic level. We can make it easier to read and drop some of the parentheses, by using the infix operator form of bind, which we get access to by locally opening Option.Monad_infix. The module is called Monad_infix because the bind operator is part of a subinterface called Monad, which we’ll see again in Chapter 16, Concurrent Programming With Async.

let compute_bounds ~compare list =
  let open Option.Monad_infix in
  let sorted = List.sort ~compare list in
  List.hd sorted   >>= fun first ->
  List.last sorted >>= fun last  ->
  Some (first,last);;
>val compute_bounds : compare:('a -> 'a -> int) -> 'a list -> ('a * 'a) option =
>  <fun>

This use of bind isn’t really materially better than the one we started with, and indeed, for small examples like this, direct matching of options is generally better than using bind. But for large, complex examples with many stages of error handling, the bind idiom becomes clearer and easier to manage.

#require "ppx_let";;
let compute_bounds ~compare list =
  let open Option.Let_syntax in
  let sorted = List.sort ~compare list in
  let%bind first = List.hd sorted in
  let%bind last  = List.last sorted in
  Some (first,last);;
>val compute_bounds : compare:('a -> 'a -> int) -> 'a list -> ('a * 'a) option =
>  <fun>

There are other useful idioms encoded in the functions in Option. One example is Option.both, which takes two optional values and produces a new optional pair that is None if either of its arguments are None. Using Option.both, we can make compute_bounds even shorter:

let compute_bounds ~compare list =
  let sorted = List.sort ~compare list in
  Option.both (List.hd sorted) (List.last sorted);;
>val compute_bounds : compare:('a -> 'a -> int) -> 'a list -> ('a * 'a) option =
>  <fun>

These error-handling functions are valuable because they let you express your error handling both explicitly and concisely. We’ve only discussed these functions in the context of the Option module, but more functionality of this kind can be found in the Result and Or_error modules. 

Helper Functions for Throwing Exceptions

Base provides a number of helper functions to simplify the task of throwing exceptions. The simplest one is failwith, which could be defined as follows:   

let failwith msg = raise (Failure msg);;
>val failwith : string -> 'a = <fun>

There are several other useful functions for raising exceptions, which can be found in the API documentation for the Common and Exn modules in Base.

Another important way of throwing an exception is the assert directive. assert is used for situations where a violation of the condition in question indicates a bug. Consider the following piece of code for zipping together two lists: 

let merge_lists xs ys ~f =
  if List.length xs <> List.length ys then None
  else
    let rec loop xs ys =
      match xs,ys with
      | [],[] -> []
      | x::xs, y::ys -> f x y :: loop xs ys
      | _ -> assert false
    in
    Some (loop xs ys);;
>val merge_lists : 'a list -> 'b list -> f:('a -> 'b -> 'c) -> 'c list option =
>  <fun>
merge_lists [1;2;3] [-1;1;2] ~f:(+);;
>- : int list option = Some [0; 3; 5]
merge_lists [1;2;3] [-1;1] ~f:(+);;
>- : int list option = None

Here we use assert false, which means that the assert, once reached, is guaranteed to trigger. In general, one can put an arbitrary condition in the assertion.

In this case, the assert can never be triggered because we have a check that makes sure that the lists are of the same length before we call loop. If we change the code so that we drop this test, then we can trigger the assert:

let merge_lists xs ys ~f =
  let rec loop xs ys =
    match xs,ys with
    | [],[] -> []
    | x::xs, y::ys -> f x y :: loop xs ys
    | _ -> assert false
  in
  loop xs ys;;
>val merge_lists : 'a list -> 'b list -> f:('a -> 'b -> 'c) -> 'c list = <fun>
merge_lists [1;2;3] [-1] ~f:(+);;
>Exception: "Assert_failure //toplevel//:6:14".

This shows what’s special about assert: it captures the line number and character offset of the source location from which the assertion was made.

Exception Handlers

So far, we’ve only seen exceptions fully terminate the execution of a computation. But sometimes, we want a program to be able to respond to and recover from an exception. This is achieved through the use of exception handlers.  

In OCaml, an exception handler is declared using a try/with expression. Here’s the basic syntax.

try <expr> with
| <pat1> -> <expr1>
| <pat2> -> <expr2>
...

A try/with clause first evaluates its body, expr. If no exception is thrown, then the result of evaluating the body is what the entire try/with clause evaluates to.

But if the evaluation of the body throws an exception, then the exception will be fed to the pattern-match clauses following the with. If the exception matches a pattern, then we consider the exception caught, and the try/with clause evaluates to the expression on the right-hand side of the matching pattern.

Otherwise, the original exception continues up the stack of function calls, to be handled by the next outer exception handler. If the exception is never caught, it terminates the program.

Cleaning Up in the Presence of Exceptions

One headache with exceptions is that they can terminate your execution at unexpected places, leaving your program in an awkward state. Consider the following function for loading a file full of numerical data. This code parses data that matches a simple comma-separated file format, where each field is a floating point number. In this example we open Stdio, to get access to routines for reading from files.   

open Stdio;;
let parse_line line =
  String.split_on_chars ~on:[','] line
  |> List.map ~f:Float.of_string;;
>val parse_line : string -> float list = <fun>
let load filename =
  let inc = In_channel.create filename in
  let data =
    In_channel.input_lines inc
    |> List.map ~f:parse_line
  in
  In_channel.close inc;
  data;;
>val load : string -> float list list = <fun>

One problem with this code is that the parsing function can throw an exception if the file in question is malformed. Unfortunately, that means that the In_channel.t that was opened will never be closed, leading to a file-descriptor leak.

We can fix this using Base’s Exn.protect function, which takes two arguments: a thunk f, which is the main body of the computation to be run; and a thunk finally, which is to be called when f exits, whether it exits normally or with an exception. This is similar to the try/finally construct available in many programming languages, but it is implemented in a library, rather than being a built-in primitive. Here’s how it could be used to fix our load function:

let load filename =
  let inc = In_channel.create filename in
  Exn.protect
    ~f:(fun () -> In_channel.input_lines inc |> List.map ~f:parse_line)
    ~finally:(fun () -> In_channel.close inc);;
>val load : string -> float list list = <fun>

This is a common enough problem that In_channel has a function called with_file that automates this pattern:

let load filename =
  In_channel.with_file filename ~f:(fun inc ->
    In_channel.input_lines inc |> List.map ~f:parse_line);;
>val load : string -> float list list = <fun>

In_channel.with_file is built on top of protect so that it can clean up after itself in the presence of exceptions.

Catching Specific Exceptions

OCaml’s exception-handling system allows you to tune your error-recovery logic to the particular error that was thrown. For example, find_exn, which we defined earlier in the chapter, throws Key_not_found when the element in question can’t be found. Let’s look at an example of how you could take advantage of this. In particular, consider the following function:   

let lookup_weight ~compute_weight alist key =
  try
    let data = find_exn alist key in
    compute_weight data
  with
  Key_not_found _ -> 0.;;
>val lookup_weight :
>  compute_weight:('a -> float) -> (string * 'a) list -> string -> float =
>  <fun>

As you can see from the type, lookup_weight takes an association list, a key for looking up a corresponding value in that list, and a function for computing a floating-point weight from the looked-up value. If no value is found, then a weight of 0. should be returned.

The use of exceptions in this code, however, presents some problems. In particular, what happens if compute_weight throws an exception? Ideally, lookup_weight should propagate that exception on, but if the exception happens to be Key_not_found, then that’s not what will happen:

lookup_weight ~compute_weight:(fun _ -> raise (Key_not_found "foo"))
["a",3; "b",4] "a";;
>- : float = 0.

This kind of problem is hard to detect in advance because the type system doesn’t tell you what exceptions a given function might throw. For this reason, it’s usually best to avoid relying on the identity of the exception to determine the nature of a failure. A better approach is to narrow the scope of the exception handler, so that when it fires it’s very clear what part of the code failed:

let lookup_weight ~compute_weight alist key =
  match
    try Some (find_exn alist key)
    with _ -> None
  with
  | None -> 0.
  | Some data -> compute_weight data;;
>val lookup_weight :
>  compute_weight:('a -> float) -> (string * 'a) list -> string -> float =
>  <fun>

This nesting of a try within a match expression is both awkward and involves some unnecessary computation (in particular, the allocation of the option). Happily, OCaml allows for exceptions to be caught by match expressions directly, which lets you write this more concisely as follows.  

let lookup_weight ~compute_weight alist key =
  match find_exn alist key with
  | exception _ -> 0.
  | data -> compute_weight data;;
>val lookup_weight :
>  compute_weight:('a -> float) -> (string * 'a) list -> string -> float =
>  <fun>

Note that the exception keyword is used to mark the exception-handling cases.

Best of all is to avoid exceptions entirely, which we could do by using the exception-free function from Base, List.Assoc.find, instead:

let lookup_weight ~compute_weight alist key =
  match List.Assoc.find ~equal:String.equal alist key with
  | None -> 0.
  | Some data -> compute_weight data;;
>val lookup_weight :
>  compute_weight:('a -> float) ->
>  (string, 'a) Base.List.Assoc.t -> string -> float = <fun>

Backtraces

A big part of the value of exceptions is that they provide useful debugging information in the form of a stack backtrace. Consider the following simple program:      

open Base
open Stdio
exception Empty_list

let list_max = function
  | [] -> raise Empty_list
  | hd :: tl -> List.fold tl ~init:hd ~f:(Int.max)

let () =
  printf "%d\n" (list_max [1;2;3]);
  printf "%d\n" (list_max [])

If we build and run this program, we’ll get a stack backtrace that will provide some information about where the error occurred and the stack of function calls that were in place at the time of the error:

dune exec -- ./blow_up.exe
>3
>Fatal error: exception Dune__exe__Blow_up.Empty_list
>Raised at Dune__exe__Blow_up.list_max in file "blow_up.ml", line 6, characters 10-26
>Called from Dune__exe__Blow_up in file "blow_up.ml", line 11, characters 16-29
[2]

You can also capture a backtrace within your program by calling Backtrace.Exn.most_recent, which returns the backtrace of the most recently thrown exception. This is useful for reporting detailed information on errors that did not cause your program to fail.  

This works well if you have backtraces enabled, but that isn’t always the case. In fact, by default, OCaml has backtraces turned off, and even if you have them turned on at runtime, you can’t get backtraces unless you have compiled with debugging symbols. Base reverses the default, so if you’re linking in Base, you will have backtraces enabled by default.

Even using Base and compiling with debugging symbols, you can turn backtraces off via the OCAMLRUNPARAM environment variable, as shown below.

OCAMLRUNPARAM=b=0 dune exec -- ./blow_up.exe
>3
>Fatal error: exception Dune__exe__Blow_up.Empty_list
[2]

The resulting error message is considerably less informative. You can also turn backtraces off in your code by calling Backtrace.Exn.set_recording false.  

There is a legitimate reason to run without backtraces: speed. OCaml’s exceptions are fairly fast, but they’re faster still if you disable backtraces. Here’s a simple benchmark that shows the effect, using the core_bench package:

open Core
open Core_bench

exception Exit

let x = 0

type how_to_end = Ordinary | Raise | Raise_no_backtrace

let computation how_to_end =
  let x = 10 in
  let y = 40 in
  let _z = x + (y * y) in
  match how_to_end with
  | Ordinary -> ()
  | Raise -> raise Exit
  | Raise_no_backtrace -> raise_notrace Exit

let computation_with_handler how = try computation how with Exit -> ()

let () =
  [
    Bench.Test.create ~name:"simple computation" (fun () ->
        computation Ordinary);
    Bench.Test.create ~name:"computation w/handler" (fun () ->
        computation_with_handler Ordinary);
    Bench.Test.create ~name:"end with exn" (fun () ->
        computation_with_handler Raise);
    Bench.Test.create ~name:"end with exn notrace" (fun () ->
        computation_with_handler Raise_no_backtrace);
  ]
  |> Bench.make_command
  |> Command_unix.run

We’re testing four cases here:      

• a simple computation with no exception,
• the same, but with an exception handler but no exception thrown,
• the same, but where an exception is thrown,
• and finally, the same, but where we throw an exception using raise_notrace, which is a version of raise which locally avoids the costs of keeping track of the backtrace.

Here are the results.

dune exec -- 
./exn_cost.exe -ascii -quota 1 -clear-columns time cycles
>Estimated testing time 4s (4 benchmarks x 1s). Change using '-quota'.
>
>  Name                    Time/Run   Cycls/Run
> ----------------------- ---------- -----------
>  simple computation        1.84ns       3.66c
>  computation w/handler     3.13ns       6.23c
>  end with exn             27.96ns      55.69c
>  end with exn notrace     11.69ns      23.28c

Note that we lose just a small number of cycles to setting up an exception handler, which means that an unused exception handler is quite cheap indeed. We lose a much bigger chunk, around 55 cycles, to actually raising an exception. If we explicitly raise an exception with no backtrace, it costs us about 25 cycles.

We can also disable backtraces, as we discussed, using OCAMLRUNPARAM. That changes the results a bit.

OCAMLRUNPARAM=b=0 dune exec -- 
./exn_cost.exe -ascii -quota 1 -clear-columns time cycles
>Estimated testing time 4s (4 benchmarks x 1s). Change using '-quota'.
>
>  Name                    Time/Run   Cycls/Run
> ----------------------- ---------- -----------
>  simple computation        1.71ns       3.41c
>  computation w/handler     3.04ns       6.05c
>  end with exn             19.36ns      38.57c
>  end with exn notrace     11.48ns      22.86c

The only significant change here is that raising an exception in the ordinary way becomes just a bit cheaper: 20 cycles instead of 55 cycles. But it’s still not as fast as using raise_notrace explicitly.

Differences on this scale should only matter if you’re using exceptions routinely as part of your flow control. That’s not a common pattern, and when you do need it, it’s better from a performance perspective to use raise_notrace. All of which is to say, you should almost always leave stack-traces on.

From Exceptions to Error-Aware Types and Back Again

Both exceptions and error-aware types are necessary parts of programming in OCaml. As such, you often need to move between these two worlds. Happily, Base comes with some useful helper functions to help you do just that. For example, given a piece of code that can throw an exception, you can capture that exception into an option as follows:   

let find alist key =
Option.try_with (fun () -> find_exn alist key);;
>val find : (string * 'a) list -> string -> 'a option = <fun>
find ["a",1; "b",2] "c";;
>- : int option = Base.Option.None
find ["a",1; "b",2] "b";;
>- : int option = Base.Option.Some 2

Result and Or_error have similar try_with functions. So, we could write:

let find alist key =
Or_error.try_with (fun () -> find_exn alist key);;
>val find : (string * 'a) list -> string -> 'a Or_error.t = <fun>
find ["a",1; "b",2] "c";;
>- : int Or_error.t = Base__.Result.Error ("Key_not_found(\"c\")")

We can then reraise that exception:

Or_error.ok_exn (find ["a",1; "b",2] "b");;
>- : int = 2
Or_error.ok_exn (find ["a",1; "b",2] "c");;
>Exception: Key_not_found("c").