avsm/oxcaml

You are writing code for the OxCaml compiler, a performance-focused fork of OCaml with Jane Street extensions. This guide covers OxCaml-specific features. You should already know standard OCaml.

Current target: OxCaml 5.2.0minus-31. The OCaml runtime reports itself as 5.2.0+ox (unchanged from 5.2.0minus-25 — the runtime base has not moved). What did change in this window is the bootstrap toolchain requirement: building OxCaml now needs upstream OCaml 5.4.0 on PATH (previously 4.14.1), via the oxcaml-dev opam package. A handful of 5.4.0 stdlib features (notably Format_doc, the caml_array_make symbol rename) were backported.

See CHANGES-25-31.md for what changed since 5.2.0minus-25, and CHANGES-23-25.md for the prior window. The upgrade guide at the bottom of CHANGES-25-31.md is the right starting point when bumping a project between these versions.

Quick Upgrade Flags (25 → 31)

When diagnosing build failures after a version bump, check these first:

• Bootstrap compiler — building OxCaml now needs upstream OCaml 5.4.0 on PATH (was 4.14.1). The OxCaml runtime itself is still 5.2.0+ox — this is only the dev-time requirement. Use the oxcaml-dev opam package per HACKING.md.
• Reserved keywords — borrow_, poly_, repr_, kind_, plus literals #true, #false, #() are now reserved. Identifiers collide → rename.
• kind_abbrev_ → kind_ — the keyword was renamed. Mechanical fix.
• Mixed block layout v4 → v5 — mixed_block_layout_v4 gone; use mixed_block_layout_v5. C macro renames to match.
• Effect low-level primitives refactored — public ('a, 'b) continuation is unchanged; internal cont gained a termination type parameter and low-level primitives were renamed. Migrate caml_alloc_stack/%runstack → %with_stack, and update %resume call sites.
• Array primitive bindings — Array.make / Array.create_float now bind to caml_array_make / caml_array_create_float. Re-promote any zero-alloc-checker expect tests. The old C symbols remain as shims, so C externals linking against them still work.
• Non-value base kinds imply mod external_ — if you need the unmoded form, use _internal (e.g. bits64_internal).
• Obj.raw_field / Obj.set_raw_field no longer external — they're now regular vals.

See CHANGES-25-31.md § Breaking Changes and Upgrade Guide for the full list and an ordered checklist.

Detailed Guides

For in-depth coverage of each feature, see:

| Feature | Guide | |---------|-------| | Modes (local, unique, once, portable, contended) | SKILL-MODES.md | | Stack Allocation (local_, stack_, exclave_) | SKILL-STACK-ALLOCATION.md | | Unboxed Types (float#, int32#, mixed blocks) | SKILL-UNBOXED.md | | Kinds (value, float64, bits32, kind products) | SKILL-KINDS.md | | Uniqueness (unique/aliased, once/many) | SKILL-UNIQUENESS.md | | Comprehensions (list/array builders) | SKILL-COMPREHENSIONS.md | | SIMD (vector types, SSE/AVX intrinsics) | SKILL-SIMD.md | | Templates (ppx_template, mangling) | SKILL-TEMPLATES.md | | Zero-Alloc ([@zero_alloc] checking) | SKILL-ZERO-ALLOC.md | | Base Library (OxCaml extensions) | SKILL-BASE.md | | Core Library (OxCaml extensions) | SKILL-CORE.md |

---

Quick Reference: Syntax Cheat Sheet

(* Stack allocation *)
let f () = exclave_ stack_ (1, 2)      (* allocate on stack, return local *)
let g (x @ local) = ...                 (* local parameter *)

(* Unboxed types *)
let x : float# = #3.14                  (* unboxed float *)
let y : int32# = #42l                   (* unboxed int32 *)
let b : bool# = #true                   (* unboxed bool (5.2.0minus-31+) *)
let u : unit# = #()                     (* unboxed unit (5.2.0minus-31+) *)
type t = { a : int; b : float# }        (* mixed block record *)

(* Modes on values *)
let f (x @ local unique once) = ...     (* multiple modes *)
val g : t @ global -> t @ local         (* in signatures *)

(* Kinds on types *)
type ('a : float64) t = ...             (* kind annotation *)
val f : ('a : value). 'a -> 'a          (* kind-polymorphic *)

(* Comprehensions *)
[ x * 2 for x = 1 to 10 when x mod 2 = 0 ]
[| y for y in arr when y > 0 |]

(* Labeled tuples *)
let pair = ~x:1, ~y:2                   (* labeled tuple *)
let ~x, ~y = pair                       (* destructuring *)

(* Immutable arrays *)
let arr : int iarray = [: 1; 2; 3 :]
let x = arr.:(0)

(* Unboxed tuple destructuring - use #(...) pattern *)
let #(a, b) = some_unboxed_pair
let #(x, y, z) = fork_join3 par f1 f2 f3

(* Zero-alloc annotation *)
let[@zero_alloc] fast_add x y = x + y

(* Borrowing (5.2.0minus-31+) - prefix form cooperating with uniqueness *)
let r = ref 0 in f (borrow_ r)          (* typical: function argument *)

(* Implicit kinds in signatures (5.2.0minus-31+) *)
module type S = sig
  [@@@implicit_kind: ('elt : word)]
  type 'elt collection                  (* 'elt defaults to kind word *)
end

---

1. Modes

Modes track runtime properties of values. Each mode axis is independent.

Mode Axes

| Axis | Values | Default | Purpose | |------|--------|---------|---------| | Locality | local, global | global | Where value lives (stack vs heap) | | Uniqueness | unique, aliased | aliased | Number of references | | Linearity | once, many | many | How often closures can be called | | Portability | portable, shareable, nonportable | nonportable | Cross-thread safety | | Contention | contended, shared, uncontended | uncontended | Thread access patterns |

Syntax

(* On parameters *)
let f (x @ local) = ...
let f (x @ local unique) = ...       (* multiple modes *)

(* On return types in signatures *)
val f : t @ local -> t @ global
val g : t @ unique once -> t @ aliased many

(* On expressions *)
let x = (expr : t @ local)

(* On let bindings *)
let local_ x = ...                    (* shorthand for local *)
let global_ x = ...

(* On record fields - modalities *)
type t = {
  global_ data : int;                 (* always global *)
  mutable x : int @@ aliased;         (* aliased modality *)
}

Subtyping Rules

More restrictive modes can be used where less restrictive are expected:

• local ≤ global (can use local where global expected? NO - reversed)
• global ≤ local (can use global where local expected)
• unique ≤ aliased (can use unique where aliased expected)
• many ≤ once (can use many where once expected)
• portable ≤ shareable ≤ nonportable
• uncontended ≤ shared ≤ contended

---

2. Stack Allocation (Locality)

Stack-allocated values avoid GC overhead but cannot escape their scope.

Key Constructs

(* Allocate on stack *)
let f () =
  let local_ x = (1, 2) in            (* stack-allocated tuple *)
  ...

(* Force stack allocation *)
let f () =
  stack_ (1, 2)                        (* explicitly stack-allocate *)

(* Return local value from function *)
let f () = exclave_
  stack_ (1, 2)                        (* return value allocated in caller's frame *)

(* Combined pattern for local returns *)
let f () = exclave_ stack_ (make_tuple ())

Rules

1. Local values CANNOT escape their defining scope (no storing in globals, no returning without exclave_)
2. Local values CAN reference global values
3. Global values CANNOT reference local values
4. exclave_ allocates in caller's stack frame and must be at tail position

Common Patterns

(* Process local data without allocation *)
let sum_pairs (pairs @ local) =
  List.fold_left (fun acc (a, b) -> acc + a + b) 0 pairs

(* Return local from function *)
let make_pair x y = exclave_ stack_ (x, y)

(* Local references for accumulators *)
let count_positives lst =
  let local_ r = ref 0 in
  List.iter (fun x -> if x > 0 then r := !r + 1) lst;
  !r

---

3. Unboxed Types

Unboxed types store values directly without heap allocation.

Built-in Unboxed Types

(* Numeric types - # suffix means unboxed *)
float#     (* 64-bit float, kind float64 *)
int32#     (* 32-bit int, kind bits32 *)
int64#     (* 64-bit int, kind bits64 *)
nativeint# (* native int, kind word *)
float32#   (* 32-bit float, kind float32 *)
int8#      (* 8-bit int - untagged, kind bits8 *)
int16#     (* 16-bit int - untagged, kind bits16 *)
int#       (* native int - untagged *)
char#      (* 8-bit char - untagged, same layout as int8# *)
bool#      (* 8-bit bool, kind bits8 (5.2.0minus-31+) *)
unit#      (* zero-size, kind void (5.2.0minus-31+) *)

(* Literals use # prefix *)
let x : float# = #3.14
let y : int32# = #42l
let z : int64# = #100L
let w : float32# = #1.0s
let a : int8# = #42s       (* int8# literal *)
let b : int16# = #42S      (* int16# literal *)
let c : char# = #'x'       (* char# literal *)
let d : bool# = #true      (* bool# literal - also #false *)
let e : unit# = #()        (* unit# literal *)

(* Boxed versions (heap-allocated) *)
let a : float = 3.14       (* boxed *)
let b : float# = #3.14     (* unboxed *)

Untagged Int Arrays (New in 5.2.0minus-25)

Arrays of untagged types are packed for memory efficiency:

(* Untagged int arrays - tightly packed *)
let bytes : int8# array = [| #0s; #1s; #255s |]
let shorts : int16# array = [| #0S; #1S; #32767S |]
let ints : int# array = [| #0; #1; #42 |]
let chars : char# array = [| #'a'; #'b'; #'c' |]

(* int8# array: 1 byte per element *)
(* int16# array: 2 bytes per element *)
(* int# array: native word size per element *)

Unboxed Records

(* Unboxed record - stored inline, not heap-allocated *)
type point = #{ x : float#; y : float# }

(* Create unboxed record *)
let p : point = #{ x = #1.0; y = #2.0 }

(* Access fields *)
let get_x (p : point) = p.#x

Unboxed Tuples

(* Unboxed tuple syntax *)
type pair = #(float# * int32#)

let p : #(float# * int32#) = #(#1.0, #42l)

Mixed Blocks

Records can mix boxed and unboxed fields:

type mixed = {
  name : string;          (* boxed *)
  value : float#;         (* unboxed, stored flat *)
  count : int32#;         (* unboxed *)
}

or_null Type

Non-allocating option for nullable values:

type 'a or_null = Null | This of 'a

(* Use for optional unboxed values without allocation *)
let find_float arr idx : float# or_null =
  if idx < Array.length arr then This arr.(idx)
  else Null

---

4. Kinds

Kinds classify types by their runtime representation.

Kind Hierarchy

any                           (* any layout *)
├── value                     (* standard OCaml boxed values *)
├── float64                   (* 64-bit floats *)
├── float32                   (* 32-bit floats *)
├── bits32                    (* 32-bit integers *)
├── bits64                    (* 64-bit integers *)
├── word                      (* native word size *)
└── void                      (* uninhabited *)

Kind Annotations

(* On type parameters *)
type ('a : float64) container = ...

(* On type variables in signatures *)
val f : ('a : value). 'a -> 'a
val g : ('a : bits64). 'a -> 'a

(* On abstract types *)
type t : float64

(* Kind products for unboxed tuples *)
type pair : float64 & bits32    (* unboxed pair of float# and int32# *)

Kind Abbreviations

value           = value_or_null mod non_null separable
immediate       = value mod external_
immediate64     = value mod external64
mutable_data    = value mod non_float
immutable_data  = value mod non_float immutable

Mode Bounds on Kinds

Kinds can specify which modes a type crosses:

(* Type that cannot be used at mode local *)
type t : value mod global

(* Type that is always portable *)
type t : value mod portable

---

5. Uniqueness

Track values with exactly one reference for safe mutation/deallocation.

Modes

• unique: Single reference exists
• aliased: Multiple references may exist

Syntax

(* Unique parameter - consumed by function *)
val free : t @ unique -> unit

(* Aliased return - may have multiple references *)
val duplicate : t -> t * t @ aliased

(* Once closures - can only be invoked once *)
val delay_free : t @ unique -> (unit -> unit) @ once

Uniqueness Rules

(* OK: match then use uniquely *)
let ok t =
  match t with
  | Con { field } -> free t

(* ERROR: using parts twice *)
let bad t =
  match t with
  | Con { field } ->
    free_field field;   (* uses field *)
    free t              (* uses t which contains field *)

(* OK: different branches *)
let ok t =
  match t with
  | Con { field } ->
    if cond then free_field field
    else free t

Aliased Modality

Store aliased values in unique containers:

type 'a aliased_box = { value : 'a @@ aliased } [@@unboxed]

(* Container is unique but contents are aliased *)
val push : 'a @ aliased -> 'a aliased_box list @ unique -> 'a aliased_box list @ unique

---

6. Comprehensions

Python/Haskell-style list and array builders.

List Comprehensions

(* Basic *)
[ x * 2 for x = 1 to 10 ]

(* With filter *)
[ x for x = 1 to 100 when x mod 2 = 0 ]

(* Nested iteration *)
[ (x, y) for x = 1 to 3 for y = 1 to 3 ]

(* Iterate over list *)
[ String.uppercase s for s in strings ]

(* Multiple conditions *)
[ x + y for x = 1 to 10 for y = 1 to 10 when x < y when x + y < 15 ]

(* Parallel iteration (evaluated together) *)
[ x + y for x = 1 to 3 and y = 10 to 12 ]

Array Comprehensions

(* Same syntax with [| |] *)
[| x * x for x = 1 to 10 |]

(* Iterate over array *)
[| f elem for elem in source_array |]

Immutable Array Comprehensions

[: x for x = 1 to 10 when x mod 2 = 0 :]

Key Differences: for vs and

• for ... for ...: Nested (inner re-evaluated each outer iteration)
• for ... and ...: Parallel (both evaluated once upfront)

(* Nested: 9 elements *)
[ (x, y) for x = 1 to 3 for y = 1 to 3 ]

(* Parallel: 3 elements *)
[ (x, y) for x = 1 to 3 and y = 10 to 12 ]
(* = [(1,10); (2,11); (3,12)] *)

---

7. SIMD Vector Types

128-bit and 256-bit SIMD vectors for parallel numeric operations.

Types

(* 128-bit vectors *)
int8x16    int8x16#      (* 16 x 8-bit ints *)
int16x8    int16x8#      (* 8 x 16-bit ints *)
int32x4    int32x4#      (* 4 x 32-bit ints *)
int64x2    int64x2#      (* 2 x 64-bit ints *)
float32x4  float32x4#    (* 4 x 32-bit floats *)
float64x2  float64x2#    (* 2 x 64-bit floats *)

(* 256-bit vectors *)
int8x32    int8x32#
int32x8    int32x8#
float64x4  float64x4#
(* etc. *)

Usage

open Ocaml_simd_sse

let v = Float32x4.set 1.0 2.0 3.0 4.0
let v = Float32x4.sqrt v
let x, y, z, w = Float32x4.splat v

(* Load from arrays *)
let v = Int8x16.String.get text ~byte:0

C Stubs

external vec_op : (int8x16[@unboxed]) -> (int8x16[@unboxed]) =
  "boxed_stub" "unboxed_stub"

---

8. Templates (ppx_template)

Generate multiple copies of code with different modes/kinds.

Mode Templates

(* Define once, get local and global versions *)
let%template[@mode m = (global, local)] id
  : 'a. 'a @ m -> 'a @ m
  = fun x -> x

(* Generates: id (global) and id__local *)

(* Instantiate *)
let f x = (id [@mode local]) x

Kind Templates

let%template[@kind k = (value, float64)] id
  : ('a : k). 'a -> 'a
  = fun x -> x

(* Generates: id (value) and id__float64 *)

Exclave Conditional

let%template[@mode m = (global, local)] make_pair x y =
  (x, y) [@exclave_if_local m]

(* local version gets: exclave_ (x, y) *)

Alloc Templates

let%template rec map
  : f:('a -> 'b @ m) -> 'a list -> 'b list @ m
  = fun ~f list ->
    match[@exclave_if_stack a] list with
    | [] -> []
    | hd :: tl -> f hd :: (map [@alloc a]) ~f tl
[@@alloc a @ m = (heap_global, stack_local)]

Portable Functors

(* Short form for portable/nonportable functor variants *)
module%template.portable Make (M : S) : T

Default Floating Attributes

[%%template:
[@@@mode.default m = (global, local)]

val min : t @ m -> t @ m -> t @ m
val max : t @ m -> t @ m -> t @ m]

---

9. Zero-Alloc Checking

Compile-time verification that functions don't allocate.

Basic Usage

(* Check function doesn't allocate *)
let[@zero_alloc] fast_add x y = x + y

(* Allow local/stack allocations *)
let[@zero_alloc] with_local_pair x y =
  let p = stack_ (x, y) in
  fst p + snd p

(* Only check in optimized builds *)
let[@zero_alloc opt] complex_func x = ...

(* Strict: no allocation even on error paths *)
let[@zero_alloc strict] very_strict x = ...

Assume Annotations

(* Trust this function is zero-alloc *)
let[@zero_alloc assume] external_wrapper x = external_func x

(* Assume for error paths *)
let[@cold][@zero_alloc assume error] handle_error e =
  log_error e;
  default_value

In Signatures

val[@zero_alloc] f : int -> int
val[@zero_alloc strict] g : t -> t
val[@zero_alloc arity 2] h : int -> int -> int

File-Level

[@@@zero_alloc all]  (* All functions must be zero-alloc *)

let[@zero_alloc ignore] allowed_to_alloc x = [x]  (* Opt out *)

---

10. Parallelism & Capsules

Safe parallel programming with thread isolation.

Contention Modes

• contended: May be accessed from multiple threads concurrently
• shared: May be accessed from multiple threads (for shared state)
• uncontended: Single-thread access

Portability Modes

• portable: Safe to move across thread boundaries, captures all values at contended
• shareable: May execute in parallel, captures shared state
• nonportable: Thread-local only, captures uncontended mutable state

Capsules (Experimental)

Capsules isolate mutable state for safe parallelism:

(* Capsule contains thread-local mutable state *)
type 'a capsule

(* Access requires entering capsule context *)
val with_capsule : 'a capsule -> ('a @ local -> 'b) -> 'b

---

11. Borrowing (5.2.0minus-31+)

The borrow_ keyword is a prefix expression form (borrow_ e) that cooperates with the uniqueness analysis. It parses anywhere an expression is valid — misuse produces mode errors, not parse errors. Typical positions where you'll actually want it:

let update_if_positive r =
  if !r > 0 then f (borrow_ r)     (* common: function argument *)

let y = borrow_ r in ...           (* let-binding RHS *)

match borrow_ r with _ -> ...      (* match scrutinee *)

Diagnostics:

• Warning 216 use-during-borrowing — "Use of a value during an active borrow." Raised when a value is used while being borrowed.
• Error Unique_use_during_borrowing — the uniqueness analysis detected a conflict between a borrow and a unique use.

Use borrow_ where a callee only reads/writes through a unique value transiently and you want to keep the unique reference after the call.

---

12. Implicit Kinds in Signatures (5.2.0minus-31+)

A floating [@@@implicit_kind: ...] attribute at the top of a signature declares that specific type-variable names default to a chosen kind. It saves repetitive per-declaration annotations:

module type Word_collection = sig
  [@@@implicit_kind: ('elt : word)]

  type 'elt collection
  val singleton : 'elt -> 'elt collection
  val length : 'elt collection -> int
end

Multiple names at once:

[@@@implicit_kind: ('a : immediate) * ('b : immediate)]
val swap : 'a * 'b -> 'b * 'a

Rules: implicit kinds can't be overridden in nested signatures, don't propagate through include, apply inside constraint clauses, and are not legal in structures. See SKILL-KINDS.md for details.

---

13. Miscellaneous Extensions

Labeled Tuples

(* Create *)
let point = ~x:10, ~y:20

(* Type *)
type point = x:int * y:int

(* Destructure *)
let ~x, ~y = point

(* Partial match (needs type annotation) *)
let get_x (p : x:int * y:int) =
  let ~x, .. = p in x

(* Function returning labeled tuple *)
val dimensions : image -> width:int * height:int

Immutable Arrays

(* Syntax uses : instead of | *)
let arr : string iarray = [: "a"; "b"; "c" :]

(* Access *)
let first = arr.:(0)

(* Covariant - allows safe subtyping *)
let arr2 : obj iarray = (arr : sub_obj iarray :> obj iarray)

Include Functor

(* Instead of *)
module M = struct
  module T = struct
    type t = ...
    [@@deriving compare, sexp]
  end
  include T
  include Comparable.Make(T)
end

(* Write *)
module M = struct
  type t = ...
  [@@deriving compare, sexp]

  include functor Comparable.Make
end

Let Mutable

(* Mutable local variable - no allocation *)
let triangle n =
  let mutable total = 0 in
  for i = 1 to n do
    total <- total + i
  done;
  total

Restrictions: Cannot escape scope, no closure capture, single variable only.

Polymorphic Parameters

(* Function taking polymorphic argument *)
let create (f : 'a. 'a field -> 'a) =
  { a = f A; b = f B }

val create : ('a. 'a field -> 'a) -> t

Small Numbers

(* Types *)
float32   float32#
int8      int8#
int16     int16#
char#

(* Literals *)
1.0s    (* float32 *)
#1.0s   (* float32# *)
42s     (* int8 *)
#42s    (* int8# *)
42S     (* int16 *)
#42S    (* int16# *)
#'a'    (* char# *)

(* Arrays - now supported and packed! *)
int8 array    int8# array     (* 1 byte per element *)
int16 array   int16# array    (* 2 bytes per element *)
char# array                   (* 1 byte per element *)

(* Pattern matching with char# ranges *)
match c with
| #'a'..#'z' -> `lowercase
| #'A'..#'Z' -> `uppercase
| _ -> `other

Module Strengthening

(* Instead of *)
sig type t = M.t end

(* Write *)
S with M

---

Common Patterns

Zero-Alloc Hot Path

let[@zero_alloc] process_batch (data @ local) =
  let local_ acc = ref 0 in
  for i = 0 to Array.length data - 1 do
    acc := !acc + process_item data.(i)
  done;
  !acc

Local Allocation in Loop

let process_all items =
  List.iter (fun item ->
    let local_ temp = compute item in
    use temp
  ) items

Unique Resource Management

type handle

val open_handle : unit -> handle @ unique
val use_handle : handle @ unique -> result * handle @ unique
val close_handle : handle @ unique -> unit

let with_handle f =
  let h = open_handle () in
  let result, h = use_handle h in
  close_handle h;
  result

Mode-Polymorphic Function

let%template[@mode m = (global, local)] map_pair f (a, b) =
  ((f a, f b) [@exclave_if_local m])

Kind-Polymorphic Container

type%template ('a : k) box = { contents : 'a }
[@@kind k = (value, float64, bits64)]

---

Debugging Tips

1. Mode errors: Check if you're trying to return local data globally
2. Kind errors: Ensure type parameters have correct layout annotations
3. Zero-alloc failures: Use -zero-alloc-checker-details-cutoff -1 for full details
4. Template issues: Check mangled names with __suffix pattern

---

Library Dependencies

Core Libraries

• stdlib_stable: Immutable arrays (Iarray), Float32, Int8, Int16, Char_u
• base: Jane Street's standard library with comprehensive OxCaml mode support
  • IMPORTANT: Consult SKILL-BASE.md for OxCaml-friendly functions!
  • Contains 116 modules with extensive local/exclave, mode, and unboxed type support
  • Key modules: Modes (modal wrappers), Iarray (immutable arrays with local ops), Container_with_local, and __local variants of most collection functions
• core: Extended library with I/O, async, and system features
  • See SKILL-CORE.md for Iobuf, Time_ns, Bigstring extensions

PPX Libraries

• ppx_template: Mode/kind polymorphism via code generation
  • See SKILL-TEMPLATES.md for mangling details
• ppx_simd: SIMD shuffle/blend mask generation

SIMD Libraries

• ocaml_simd: Base SIMD types
• ocaml_simd_sse: SSE intrinsics (128-bit)
• ocaml_simd_avx: AVX/AVX2 intrinsics (256-bit)
• See SKILL-SIMD.md for usage details