Thomas Letan's Blog - coqffi

What happened in October and November 2022?

November 19, 2022

What happened in October and November 2022?

It is November 19 today, and I’m one month and 4 days late for the October Retrospective! Truth is, $WORK has been intense lately, to a point where I have not made much progress on my side projects. Anyway.

I have implemented the last feature I was really missing in my daily use of Spatial Sway: moving windows to adjacent workspaces. As a result, I think I can say that Spatial Sway has really reached the “Minimum Viable Product” stage, with a convenient UX, and a nice enough UI. It is still lacking when it comes to configurability, though. It is the next item of my TODO list, but I have no idea when I will implement the support for a configuration file.

Another highlight of the past two months was the NaNoWriMo . I took the last week of October and the first week of November off to plan and start writing a fiction project for it. Writing again was really nice, and I even gave writing fiction in English a shot. That made me uncover a bug in the English support of ogam , my markup language for fiction writers, which led me to publish a fix on Crates.io. However, as soon as I came back to $WORK, my writing spree ended. That’s okay, though. It gave me plenty of ideas for future sessions. Thanks, NaNoWriMo! Sorry to quit so soon, and see you next year, maybe.

Finally, a nice surprise of the past month is that someone has started working on adding proper support for coqffi to dune , the build system for OCaml and Coq! I’m thrilled by this. Thanks, @Alizter !

This wraps up this retrospective. I hope I will have more interesting, concrete news to share next month.

Implementing an Echo Server in Coq with coqffi.1.0.0

December 10, 2020

Implementing an Echo Server in Coq with `coqffi.1.0.0`

coq ocaml coqffi

In this article, we will demonstrate how coqffi can be used to implement an echo server, i.e., a TCP server which sends back any input it receives from its clients. In addition to coqffi, you will need to install coq-simple-io. The latter is available in the released repository of the Opam Coq Archive .

opam install coq-coqffi coq-simple-io

Besides, you can download the source tree presented in this article if you want to try to read the source directly, or modify it to your taste.

Project Layout

Before diving too much into the implementation of our echo server, we first give an overview of the resulting project’s layout. Since we aim at implementing a program, we draw our inspiration from the idiomatic way of organizing a OCaml project.

We have three directories at the root of the project.

ffi/ contains the low-level OCaml code: It provides an OCaml library (ffi), and a Coq theory (FFI) which gathers the FFI modules generated by coqffi.
src/ contains the Coq implementation of our echo server: It provides a Coq theory (Echo) which depends on the FFI theory the SimpleIO theory of coq-simple~io. This theory provides the implementation of our echo server in Coq.
bin/ contains the pieces of code to get an executable program: It contains a Coq module (echo.v) which configures and uses the extraction mechanism to generate an OCaml module (echo.ml). This OCaml module can be compiled to get an executable program.

Note that we could have decided to only have one Coq theory. We could also have added a fourth directory (theories/) for formal verification specific code, but this is out of the scope of this tutorial.

Overall, we use dune to compile and compose the different parts of the echo server. dune has a native —yet unstable at the time of writing— support for building Coq projects, with very convenient stanzas like coq.theory and coq.extraction.

The following graph summarizes the dependencies between each component (plain arrows symbolize software dependencies).

The echo server dependency graph. Dashed boxes are generated.

We enable Coq-related stanza with (using coq 0.2) in the dune-project. file.

(lang dune 2.7)
(using coq 0.2)

The rest of this tutorial proceeds by diving into each directory.

FFI Bindings

Our objective is to implement an echo server, i.e., a server which (1) accepts incoming connections, and (2) sends back any incoming messages. We will consider two classes of effects. One is related to creating and manipulating TCP sockets. The other is dedicated to process management, more precisely to be able to fork when receiving incoming connections.

Therefore, the ffi library will provide two modules. Likewise, the FFI theory will provide two analogous modules generated by coqffi.

In the ffi/ directory, we add the following stanza to the dune file.

(library
  (name ffi)
  (libraries unix))

dune will look for any .ml and .mli files within the directory and will consider they belong to the ffi library. We use the unix library to implement the features we are looking for.

Then, we add the following stanza to the dune file of the ffi/ directory.

(coq.theory
  (name FFI))

This tells dune to look for .v file within the ffi/ directory, in order to build them with Coq. A nice feature of dune is that if we automatically generate Coq files, they will be automatically “attached” to this theory.

Sockets

Sockets are boring. The following OCaml module interface provides the necessary type and functions to manipulate them.

type socket_descr

val open_socket : string -> int -> socket_descr
val listen : socket_descr -> unit
val recv : socket_descr -> string
val send : socket_descr -> string -> int
val accept_connection : socket_descr -> socket_descr
val close_socket : socket_descr -> unit

Our focus is how to write the interface modules for coqffi. Since the object of this tutorial is not the implementation of an echo server in itself, the implementation details of the ffi library will not be discussed, but is provided at the end of this article.

dune generates .cmi files for the .mli files of our library, and provides the necessary bits to easily locate them. Besides, the action stanza can be used here to tell to dune how to generate the module Socket.v from file.cmi. We add the following entry to ffi/dune.

(rule
  (target Socket.v)
  (action (run coqffi %{cmi:socket} -o %{target})))

We call coqffi without any feature-related command-line argument, which means only the simple-io feature is enabled. As a consequence, the socket_descr type is axiomatized in Coq, and in addition to a MonadSocket monad, coqffi will generate an instance for this monad for the IO monad of coq-simple-io.

The stanza generates the following Coq module.

(* This file has been generated by coqffi. *)

Set Implicit Arguments.
Unset Strict Implicit.
Set Contextual Implicit.
Generalizable All Variables.
Close Scope nat_scope.

From CoqFFI Require Export Extraction.
From SimpleIO Require Import IO_Monad.

Axiom socket_descr : Type.

Extract Constant socket_descr => "Ffi.Socket.socket_descr".

(** * Impure Primitives *)

(** ** Monad Definition *)

Class MonadSocket (m : Type -> Type) : Type :=
  { open_socket : string -> i63 -> m socket_descr
  ; listen : socket_descr -> m unit
  ; recv : socket_descr -> m string
  ; send : socket_descr -> string -> m i63
  ; accept_connection : socket_descr -> m socket_descr
  ; close_socket : socket_descr -> m unit
  }.

(** ** [IO] Instance *)

Axiom io_open_socket : string -> i63 -> IO socket_descr.
Axiom io_listen : socket_descr -> IO unit.
Axiom io_recv : socket_descr -> IO string.
Axiom io_send : socket_descr -> string -> IO i63.
Axiom io_accept_connection : socket_descr -> IO socket_descr.
Axiom io_close_socket : socket_descr -> IO unit.

Extract Constant io_open_socket
  => "(fun x1 x2 k__ -> k__ ((Ffi.Socket.open_socket x1 x2)))".
Extract Constant io_listen => "(fun x1 k__ -> k__ ((Ffi.Socket.listen x1)))".
Extract Constant io_recv => "(fun x1 k__ -> k__ ((Ffi.Socket.recv x1)))".
Extract Constant io_send
  => "(fun x1 x2 k__ -> k__ ((Ffi.Socket.send x1 x2)))".
Extract Constant io_accept_connection
  => "(fun x1 k__ -> k__ ((Ffi.Socket.accept_connection x1)))".
Extract Constant io_close_socket
  => "(fun x1 k__ -> k__ ((Ffi.Socket.close_socket x1)))".

Instance IO_MonadSocket : MonadSocket IO :=
  { open_socket := io_open_socket
  ; listen := io_listen
  ; recv := io_recv
  ; send := io_send
  ; accept_connection := io_accept_connection
  ; close_socket := io_close_socket
  }.

(* The generated file ends here. *)

Process Management

In order to avoid a client to block the server by connecting to it without sending anything, we can fork a new process for each client.

type identity = Parent of int | Child

val fork : unit -> identity

This time, the proc.mli module interface introduces a transparent type, /i.e./, it also provides its definition. This is a good use case for the transparent-types feature of coqffi. In the stanza for generating Proc.v, we enable it with the -ftransparent-types command-line argument, like this.

(rule
  (target Proc.v)
  (action (run coqffi -ftransparent-types %{cmi:proc} -o %{target})))

which generates the following Coq module.

(* This file has been generated by coqffi. *)

Set Implicit Arguments.
Unset Strict Implicit.
Set Contextual Implicit.
Generalizable All Variables.
Close Scope nat_scope.

From CoqFFI Require Export Extraction.
From SimpleIO Require Import IO_Monad.

Inductive identity : Type :=
| Parent (x0 : i63) : identity
| Child : identity.

Extract Inductive identity => "Ffi.Proc.identity"
  [ "Ffi.Proc.Parent" "Ffi.Proc.Child" ].

(** * Impure Primitives *)

(** ** Monad Definition *)

Class MonadProc (m : Type -> Type) : Type := { fork : unit -> m identity
                                             }.

(** ** [IO] Instance *)

Axiom io_fork : unit -> IO identity.

Extract Constant io_fork => "(fun x1 k__ -> k__ ((Ffi.Proc.fork x1)))".

Instance IO_MonadProc : MonadProc IO := { fork := io_fork
                                        }.

(* The generated file ends here. *)

We now have everything we need to implement an echo server in Coq.

Implementing an Echo Server

Our implementation will be part of a dedicated Coq theory, called Echo. This is done easily a dune file in the src/ directory, with the following content.

(coq.theory
  (name Echo)
  (theories FFI))

In the rest of this section, we will discuss the content of the unique module of this theory. Hopefully, readers familiar with programming impurity by means of monads will not find anything particularly surprising here.

Let us start with the inevitable sequence of import commands. We use the Monad and MonadFix typeclasses of ExtLib, and our FFI modules from the FFI theory we have previously defined.

From ExtLib Require Import Monad MonadFix.
From FFI Require Import Proc Socket.

Letting Coq guess the type of unintroduced variables using the ` annotation (e.g., in presence of `{Monad m}, Coq understands m is of type Type -> Type) is always nice, so we enable it.

Generalizable All Variables.

We enable the monad notation provided by ExtLib. In this article, we prefer the let* notation (as recently introduced by OCaml) over the <- notation of Haskell, but both are available.

Import MonadLetNotation.
Open Scope monad_scope.

Then, we define a notation to be able to define local, monadic recursive functions using the mfix combinator of the MonadFix typeclass.

Notation "'let_rec*' f x ':`' p 'in' q" :`
  (let f :` mfix (fun f x `> p) in q)
    (at level 61, x pattern, f name, q at next level, right associativity).

Note that mfix does /not/ check whether or not the defined function will terminate (contrary to the fix keyword of Coq). This is fortunate because in our case, we do not want our echo server to converge, but rather to accept an infinite number of connections.

We can demonstrate how this notation can be leveraged by defining a generic TCP server, parameterized by a handler to deal with incoming connections.

Definition tcp_srv `{Monad m, MonadFix m, MonadProc m, MonadSocket m}
    (handler : socket_descr -> m unit)
  : m unit :=
  let* srv := open_socket "127.0.0.1" 8888 in
  listen srv;;

  let_rec* tcp_aux _ :=
    let* client := accept_connection srv in
    let* res := fork tt in
    match res with
    | Parent _ => close_socket client >>= tcp_aux
    | Child =>  handler client
    end
  in

  tcp_aux tt.

The handler for the echo server is straightforward: it just reads incoming bytes from the socket, sends it back, and closes the socket.

Definition echo_handler `{Monad m, MonadSocket m} (sock : socket_descr)
  : m unit :=
  let* msg := recv sock in
  send sock msg;;
  close_socket sock.

Composing our generic TCP server with our echo handler gives us an echo server.

Definition echo_server `{Monad m, MonadFix m, MonadProc m, MonadSocket m}
  : m unit :=
  tcp_srv echo_handler.

Because coqffi has generated typeclasses for the impure primitives of proc.mli and socket.mli, echo_server is polymorphic, and can be instantiated for different monads. When it comes to extracting our program, we will generally prefer the IO monad of coq-simple-io. But we could also imagine verifying the client handler with FreeSpec, or the generic TCP server with Interaction Trees (which support diverging computations). Overall, we can have different verification strategies for different parts of our program, by leveraging the most relevant framework for each part, yet being able to extract it in an efficient form.

The next section shows how this last part is achieved using, once again, a convenient stanza of dune.

Extracting and Building an Executable

The 0.2 version of the Coq-related stanzas of dune provides the coq.extraction stanza, which can be used to build a Coq module expected to generate ml files.

In our case, we will write bin/echo.v to extract the echo_server in a echo.ml module, and uses the executable stanza of dune to get an executable from this file. To achieve this, the bin/dune file simply requires these two stanzas.

(coq.extraction
  (prelude echo)
  (theories Echo)
  (extracted_modules echo))

(executable
  (name echo)
  (libraries ffi))

We are almost done. We now need to write the echo.v module, which mostly consists of (1) providing a MonadFix instance for the IO monad, (2) using the IO.unsafe_run function to escape the IO monad, (3) calling the Extraction command to wrap it up.

From Coq Require Extraction.
From ExtLib Require Import MonadFix.
From SimpleIO Require Import SimpleIO.
From Echo Require Import Server.

Instance MonadFix_IO : MonadFix IO :=
  { mfix := @IO.fix_io }.

Definition main : io_unit :=
  IO.unsafe_run echo_server.

Extraction "echo.ml" main.

Since we are using the i63 type (signed 63bits integers) of the CoqFFI theory, and since i63 is implemented under the hood with Coq primitive integers, we also need to provide a Uint63 module with a of_int function. Fortunately, this module is straightforward to write.

let of_int x = x

And voilà. A call to dune at the root of the repository will build everything (Coq and OCaml alike). Starting the echo server is as simple as

dune exec bin/echo.exe

And connecting to it can be achieved with a program like telnet.

$ telnet 127.0.0.1 8888
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
hello, echo server!
hello, echo server!
Connection closed by foreign host.

Appendix

The `Socket` OCaml Module

There is not much to say, except that (as already stated) we use the Unix module to manipulate sockets, and we attach to each socket a buffer to store incoming bytes.

let buffer_size = 1024

type socket_descr = {
  fd : Unix.file_descr;
  recv_buffer : bytes;
}

let from_fd fd =
  let rbuff = Bytes.create buffer_size in
  { fd ` fd; recv_buffer ` rbuff }

let open_socket hostname port =
  let open Unix in
  let addr = inet_addr_of_string hostname in
  let fd = socket PF_INET SOCK_STREAM 0 in
  setsockopt fd SO_REUSEADDR true;
  bind fd (ADDR_INET (addr, port));
  from_fd fd

let listen sock = Unix.listen sock.fd 1

let recv sock =
  let s = Unix.read sock.fd sock.recv_buffer 0 buffer_size in
  Bytes.sub_string sock.recv_buffer 0 s

let send sock msg =
  Unix.write_substring sock.fd msg 0 (String.length msg)

let accept_connection sock =
  Unix.accept sock.fd |> fst |> from_fd

let close_socket sock = Unix.close sock.fd

The `Proc` OCaml Module

Thanks to the Unix module, the implementation is pretty straightforward.

type identity = Parent of int | Child

let fork x =
  match Unix.fork x with
  | 0 -> Child
  | x -> Parent x

coqffi.1.0.0 In A Nutshell

December 10, 2020

`coqffi.1.0.0` In A Nutshell

coq ocaml coqffi

For each entry of a cmi file (a compiled mli file), coqffi tries to generate an equivalent (from the extraction mechanism perspective) Coq definition. In this article, we walk through how coqffi works.

Note that we do not dive into the vernacular commands coqffi generates. They are of no concern for users of coqffi.

Getting Started

Requirements

The latest version of coqffi (1.0.0~beta8) is compatible with OCaml 4.08 up to 4.14, and Coq 8.12 up top 8.13. If you want to use coqffi, but have incompatible requirements of your own, feel free to submit an issue .

Installing `coqffi`

The recommended way to install coqffi is through the Opam Coq Archive , in the released repository. If you haven’t activated this repository yet, you can use the following bash command.

opam repo add coq-released https://coq.inria.fr/opam/released

Then, installing coqffi is as simple as

opam install coq-coqffi

You can also get the source from the upstream git repository . The README provides the necessary pieces of information to build it from source.

Additional Dependencies

One major difference between Coq and OCaml is that the former is pure, while the latter is not. Impurity can be modeled in pure languages, and Coq does not lack of frameworks in this respect. coqffi currently supports two of them: coq-simple-io and FreeSpec . It is also possible to use it with Interaction Trees , albeit in a less direct manner.

Primitive Types

coqffi supports a set of primitive types, i.e., a set of OCaml types for which it knows an equivalent type in Coq. The list is the following (the Coq types are fully qualified in the table, but not in the generated Coq module as the necessary Import statements are generated too).

OCaml type	Coq type
`bool`	`Coq.Init.Datatypes.bool`
`char`	`Coq.Strings.Ascii.ascii`
`int`	`CoqFFI.Data.Int.i63`
`'a list`	`Coq.Init.Datatypes.list a`
`'a Seq.t`	`CoqFFI.Data.Seq.t`
`'a option`	`Coq.Init.Datatypes.option a`
`('a, 'e) result`	`Coq.Init.Datatypes.sum`
`string`	`Coq.Strings.String.string`
`unit`	`Coq.Init.Datatypes.unit`
`exn`	`CoqFFI.Exn`

The i63 type is introduced by the CoqFFI theory to provide signed primitive integers to Coq users. They are implemented on top of the (unsigned) Coq native integers introduced in Coq 8.13. The i63 type will be deprecated once the support for signed primitive integers is implementedThis is actually one of the sources of incompatibility of coqffi with most recent versions of Coq. .

When processing the entries of a given interface model, coqffi will check that they only use these types, or types introduced by the interface module itself.

Sometimes, you may encounter a situation where you have two interface modules b.mli and b.mli, such that b.mli uses a type introduced in a.mli. To deal with this scenario, you can use the --witness flag to generate A.v. This will tell coqffi to also generate A.ffi; this file can then be used when generating B.v thanks to the -I option. Furthermore, for B.v to compile the --require option needs to be used to ensure the A Coq library (A.v) is required.

To give a more concrete example, given ~a.mli~

type t

and b.mli

type a = A.t

To generate A.v, we can use the following commands:

ocamlc a.mli
coqffi --witness -o A.v a.cmi

Which would generate the following axiom for t.

Axiom t : Type.

Then, generating B.v can be achieved as follows:

ocamlc b.mli
coqffi -I A.ffi -ftransparent-types -r A -o B.v b.cmi

which results in the following output for v:

Require A.

Definition u : Type := A.t.

Code Generation

coqffi distinguishes five types of entries: types, pure values, impure primitives, asynchronous primitives, exceptions, and modules. We now discuss how each one of them is handled.

Types

By default, coqffi generates axiomatized definitions for each type defined in a .cmi file. This means that type t becomes Axiom t : Type. Polymorphism is supported, i.e., type 'a t becomes Axiom t : forall (a : Type), Type.

It is possible to provide a “model” for a type using the coq_model annotation, for instance, for reasoning purposes. That is, we can specify that a type is equivalent to a list.

type 'a t [@@coq_model "list"]

This generates the following Coq definition.

Definition t : forall (a : Type), Type := list.

It is important to be careful when using the =coq_model= annotation. More precisely, the fact that t is a list in the “Coq universe” shall not be used while the implementation phase, only the verification phase.

Unnamed polymorphic type parameters are also supported. In presence of such parameters, coqffi will find it a name that is not already used. For instance,

type (_, 'a) ast

becomes

Axiom ast : forall (b : Type) (a : Type), Type.

Finally, coqffi has got an experimental feature called transparent-types (enabled by using the -ftransparent-types command-line argument). If the type definition is given in the module interface, then coqffi tries to generate an equivalent definition in Coq. For instance,

type 'a llist =
  | LCons of 'a * (unit -> 'a llist)
  | LNil

becomes

Inductive llist (a : Type) : Type :=
| LCons (x0 : a) (x1 : unit -> llist a) : llist a
| LNil : llist a.

Mutually recursive types are supported, so

type even = Zero | ESucc of odd
and odd = OSucc of even

becomes

Inductive odd : Type :=
| OSucc (x0 : even) : odd
with even : Type :=
| Zero : even
| ESucc (x0 : odd) : even.

Besides, coqffi supports alias types, as suggested in this write-up when we discuss witness files.

The transparent-types feature is experimental, and is currently limited to variant types. It notably does not support records. Besides, it may generate incorrect Coq types, because it does not check whether or not the positivity condition is satisfied.

Pure values

coqffi decides whether or not a given OCaml value is pure or impure with the following heuristics:

Constants are pure
Functions are impure by default
Functions with a coq_model annotation are pure
Functions marked with the pure annotation are pure
If the pure-module feature is enabled (-fpure-module), then synchronous functions (which do not live inside the ~Lwt~ monad) are pure

Similarly to types, coqffi generates axioms (or definitions if the coq_model annotation is used) for pure values. Then,

val unpack : string -> (char * string) option [@@pure]

becomes

Axiom unpack : string -> option (ascii * string).

Polymorphic values are supported.

val map : ('a -> 'b) -> 'a list -> 'b list [@@pure]

becomes

Axiom map : forall (a : Type) (b : Type), (a -> b) -> list a -> list b.

Again, unnamed polymorphic typse are supported, so

val ast_to_string : _ ast -> string [@@pure]

becomes

Axiom ast_to_string : forall (a : Type), string.

Impure Primitives

coqffi reserves a special treatment for /impure/ OCaml functions. Impurity is usually handled in pure programming languages by means of monads, and coqffi is no exception to the rule.

Given the set of impure primitives declared in an interface module, coqffi will (1) generate a typeclass which gathers these primitives, and (2) generate instances of this typeclass for supported backends.

We illustrate the rest of this section with the following impure primitives.

val echo : string -> unit
val scan : unit -> string

where echo allows writing something the standard output, and scan to read the standard input.

Assuming the processed module interface is named console.mli, the following Coq typeclass is generated.

Class MonadConsole (m : Type -> Type) := { echo : string -> m unit
                                         ; scan : unit -> m string
                                         }.

Using this typeclass and with the additional support of an additional Monad typeclass, we can specify impure computations which interacts with the console. For instance, with the support of ExtLib, one can write.

Definition pipe `{Monad m, MonadConsole m} : m unit :=
  let* msg := scan () in
  echo msg.

There is no canonical way to model impurity in Coq, but over the years several frameworks have been released to tackle this challenge.

coqffi provides three features related to impure primitives.

`simple-io`

When this feature is enabled, coqffi generates an instance of the typeclass for the =IO= monad introduced in the coq-simple-io package

Axiom io_echo : string -> IO unit.
Axiom io_scan : unit -> IO string.

Instance IO_MonadConsole : MonadConsole IO := { echo := io_echo
                                              ; scan := io_scan
                                              }.

It is enabled by default, but can be disabled using the -fno-simple-io command-line argument.

`interface`

When this feature is enabled, coqffi generates an inductive type which describes the set of primitives available, to be used with frameworks like FreeSpec or Interactions Trees .

Inductive CONSOLE : Type -> Type :=
| Echo : string -> CONSOLE unit
| Scan : unit -> CONSOLE string.

Definition inj_echo `{Inject CONSOLE m} (x0 : string) : m unit :=
  inject (Echo x0).

Definition inj_scan `{Inject CONSOLE m} (x0 : unit) : m string :=
  inject (Scan x0).

Instance Inject_MonadConsole `{Inject CONSOLE m} : MonadConsole m :=
  { echo := inj_echo
  ; scan := inj_scan
  }.

Providing an instance of the form forall i, Inject i M is enough for your monad M to be compatible with this featureSee for instance how FreeSpec implements it ). .

`freespec`

When this feature in enabled, coqffi generates a semantics for the inductive type generated by the interface feature.

Axiom unsafe_echo : string -> unit.
Axiom unsafe_scan : uint -> string.

Definition console_unsafe_semantics : semantics CONSOLE :=
  bootstrap (fun a e =>
    local match e in CONSOLE a return a with
          | Echo x0 => unsafe_echo x0
          | Scan x0 => unsafe_scan x0
          end).

Asynchronous Primitives

coqffi also reserves a special treatment for asynchronous primitives —i.e., functions which live inside the Lwt monad— when the lwt feature is enabled.

The treatment is very analogous to the one for impure primitives: (1) a typeclass is generated (with the _Async suffix), and (2) an instance for the Lwt monad is generated. Besides, an instance for the “synchronous” primitives is also generated for Lwt. If the interface feature is enabled, an interface datatype is generated, which means you can potentially use Coq to reason about your asynchronous programs (using FreeSpec and alike, although the interleaving of asynchronous programs in not yet supported in FreeSpec).

By default, the type of the Lwt monad is Lwt.t. You can override this setting using the --lwt-alias option. This can be useful when you are using an alias type in place of Lwt.t.

Exceptions

OCaml features an exception mechanism. Developers can define their own exceptions using the exception keyword, whose syntax is similar to the constructors’ definition. For instance,

exception Foo of int * bool

introduces a new exception Foo which takes two parameters of type int and bool. Foo (x, y) constructs of value of type exn.

For each new exception introduced in an OCaml module, coqffi generates (1) a so-called “proxy type,” and (2) conversion functions to and from this type.

Coming back to our example, the “proxy type” generates by coqffi is

Inductive FooExn : Type :=
| MakeFooExn (x0 : i63) (x1 : bool) : FooExn.

Then, coqffi generates conversion functions.

Axiom exn_of_foo : FooExn -> exn.
Axiom foo_of_exn : exn -> option FooExn.

Besides, coqffi also generates an instance for the Exn typeclass provided by the CoqFFI theory:

Instance FooExn_Exn : Exn FooExn :=
  { to_exn := exn_of_foo
  ; of_exn := foo_of_exn
  }.

Under the hood, exn is an extensible datatype , and how coqffi supports it will probably be generalized in future releases.

Finally, coqffi has a minimal support for functions which may raise exceptions. Since OCaml type system does not allow to identify such functions, they need to be annotated explicitly, using the =may_raise= annotation. In such a case, coqffi will change the return type of the function to use the =sum= Coq inductive type.

For instance,

val from_option : 'a option -> 'a [@@may_raise] [@@pure]

becomes

Axiom from_option : forall (a : Type), option a -> sum a exn.

Modules

Lastly, coqffi supports OCaml modules described within mli files, when they are specified as module T : sig ... end. For instance,

module T : sig
  type t

  val to_string : t -> string [@@pure]
end

becomes

Module T.
  Axiom t : Type.

  Axiom to_string : t -> string.
End T.

As of now, the following construction is unfortunately not supported, and will be ignored by coqffi:

module S = sig
  type t

  val to_string : t -> string [@@pure]
end

module T : S

Moving Forward

coqffi comes with a comprehensive man page. In addition, the interested reader can proceed to the next article of this series, which explains how coqffi can be used to easily implement an echo server in Coq.

Thomas Letan's Blog - coqffi

What happened in October and November 2022?

What happened in October and November 2022?

Implementing an Echo Server in Coq with coqffi.1.0.0

Implementing an Echo Server in Coq with coqffi.1.0.0

Project Layout

FFI Bindings

Sockets

Process Management

Implementing an Echo Server

Extracting and Building an Executable

Appendix

The Socket OCaml Module

The Proc OCaml Module

coqffi.1.0.0 In A Nutshell

coqffi.1.0.0 In A Nutshell

Getting Started

Requirements

Installing coqffi

Additional Dependencies

Primitive Types

Code Generation

Types

Pure values

Impure Primitives

simple-io

interface

freespec

Asynchronous Primitives

Exceptions

Modules

Moving Forward

Implementing an Echo Server in Coq with `coqffi.1.0.0`

The `Socket` OCaml Module

The `Proc` OCaml Module

`coqffi.1.0.0` In A Nutshell

Installing `coqffi`

`simple-io`

`interface`

`freespec`