(* local values can be stack-allocated, global values must be heap-allocated *)
let f (x @ local) = ...           (* local parameter - won't escape *)
val f : 'a @ local -> unit        (* type signature *)

let x = stack_ { foo; bar }       (* force stack allocation *)
let f a = exclave_ ...            (* return stack-allocated value to caller's region *)
type 'a t = { g : 'a @@ global }  (* field always heap-allocated *)

(* portable: can cross thread boundaries; nonportable: cannot *)
val f : t @ contended -> float @@ portable   (* @ for params, @@ for returns *)

(* contended: another thread may write; shared: read-only; uncontended: single thread *)
(* Mutable fields of contended values cannot be accessed *)

(* unique: only one reference exists; aliased: multiple references may exist *)
(* once: can only be used once; many: can be used multiple times *)

(* Types: float#, int32#, int64#, nativeint#, float32# *)
(* Layouts: float64, bits32, bits64, word, float32 *)

let pi = #3.14          (* float# *)
let x = #123l           (* int32# *)
let y = -#456L          (* int64# *)
let z = #789n           (* nativeint# *)

(* Canonical module aliases from Unboxed library *)
open Unboxed
(* F64 = Float_u, F32 = Float32_u, I64 = Int64_u, I32 = Int32_u, Iptr = Nativeint_u *)
(* UFO = Unboxed float option (packed), Pct = Percent_u *)

(* Conversion to/from boxed types *)
let unboxed : int64# = I64.of_int64 42L
let boxed : int64 = I64.to_int64 unboxed

(* Arithmetic - all operations are [@zero_alloc] *)
(* Use .O submodule for operators - opens fewer names into scope *)
let sum = I64.O.(#1L + #2L)
let product = I64.O.(#3L * #4L)
let quotient = I64.O.(#10L / #3L)      (* integer division *)
let remainder = I64.O.(#10L % #3L)     (* modulo *)
let power = I64.O.(#2L ** #10L)        (* exponentiation *)
let float_div = I64.O.(#10L // #3L)    (* returns float# *)

(* Bit operations *)
let bits = I64.(bit_and #0xFFL #0x0FL)
let shifted = I64.(shift_left #1L 4)
let popcnt = I64.popcount #0b10101L
let leading = I64.clz #0x00FFL         (* count leading zeros *)
let trailing = I64.ctz #0x0100L        (* count trailing zeros *)

(* Comparisons *)
let cmp = I64.O.(#5L > #3L)
let eq = I64.equal #1L #1L
let ord = I64.compare #1L #2L
let bounded = I64.between #5L ~low:#0L ~high:#10L
let clamped = I64.clamp_exn #15L ~min:#0L ~max:#10L

(* Power-of-2 operations *)
let next_pow2 = I64.ceil_pow2 #5L      (* #8L *)
let log2 = I64.floor_log2 #8L          (* 3 *)
let is_pow = I64.is_pow2 #8L           (* true *)

(* Rounding *)
let rounded = I64.round ~dir:`Nearest #7L

(* Unboxed arrays - efficient storage without boxing *)
let arr : int64# array = I64.Array.create ~len:10 #0L
let () = I64.Array.set arr 0 #42L
let v = I64.Array.get arr 0

(* Unboxed refs - mutable unboxed values *)
let counter : I64.Ref.t = I64.Ref.create #0L
let () = I64.Ref.set counter #1L
let current = I64.Ref.get counter

(* UFO uses NaN to represent None - no allocation overhead *)
let some_val : UFO.t = UFO.some #3.14
let none_val : UFO.t = UFO.none ()
let is_present = UFO.is_some some_val
let value = UFO.value_exn some_val
let with_default = UFO.value none_val ~default:#0.0

(* Safe operations that propagate None *)
let result = UFO.O.(some #1.0 + some #2.0)   (* some #3.0 *)
let propagate = UFO.O.(some #1.0 + none ())  (* none *)

(* Convert NaN to None *)
let safe = UFO.of_float_nan_as_none #(Float.nan)  (* none *)

(* Specify the module path inline (preferred) *)
(* match%optional.Module for boxed, match%optional_u.Module for unboxed *)

(* Basic usage with unboxed float options *)
let[@zero_alloc] value_or_zero (t : UFO.t) =
  match%optional_u.Packed_float_option.Unboxed t with
  | None -> UFO.zero ()
  | Some x -> x

(* Multiple values *)
let[@zero_alloc] merge x y ~f =
  match%optional_u.Packed_float_option.Unboxed x, y with
  | None, None -> UFO.none ()
  | Some x, None -> x
  | None, Some y -> y
  | Some x, Some y -> f x y

(* Boxed Packed_float_option.t uses match%optional (no _u) *)
let hash (t : Packed_float_option.t) =
  match%optional.Packed_float_option t with
  | None -> none_hash
  | Some t -> Float.hash t

(* With local mode for stack-allocated values *)
let[@zero_alloc] value_local (t : UFO.t @ local) ~default =
  match%optional_u.Packed_float_option.Unboxed (t : _ @ local) with
  | None -> default
  | Some x -> x

(* Unboxed percentage type *)
let pct = Pct.of_percentage #5.0       (* 5% *)
let mult = Pct.to_mult pct             (* #0.05 *)
let bp = Pct.of_bp #50L                (* 50 basis points = 0.5% *)

let applied = Pct.apply pct #100.0     (* #5.0 *)
let scaled = Pct.scale pct #2.0        (* 10% *)

type ('a : immediate) t1              (* type variable with layout *)
type ('a : float64) t2
type t : float64                      (* type with layout *)

let f (type a : immediate) (x : a) = x
val f : ('a : float64). 'a -> 'a      (* universally quantified layout *)

(* Unboxed tuples - passed in registers, no heap allocation *)
let flip #(x, y, ~lbl:z) = #(~lbl:z, y, x)
type t = #(int * float# * lbl:string)

(* Unboxed records - flat layout, passed in registers *)
type t = #{ f : float# ; s : string }
let inc #{ f ; s } = #{ f = F64.O.(f + #1.0) ; s }

(* Field access uses .# syntax *)
let get_f t = t.#f                    (* projection with .# *)
let get_s t = t.#s

(* Construction uses #{ ... } *)
let make f s = #{ f; s }

(* No "with" syntax - must reconstruct all fields *)
let set_f t new_f = #{ f = new_f; s = t.#s }

(* Implicit unboxed records - t# auto-generated from t *)
type t = { i : int ; s : string }
let box : t# -> t = fun #{ i ; s } -> { i ; s }

(* Problem: failwith returns 'a : value, but we need value & bits64 & bits64 *)
let slice_exn t ~pos ~len : Slice.t =
  if pos < #0L
  then failwith "bad pos"  (* Error: layout mismatch *)
  else ...

(* Solution: match on never_returns to satisfy the type checker *)
let slice_exn t ~pos ~len : Slice.t =
  if pos < #0L
  then (match failwith "bad pos" with (_ : never_returns) -> .)
  else ...

type 'a or_null : value_or_null
(* Constructors: Null, This v *)

let arr = [| #2l |]                   (* int32# array *)

(* Use [@layout_poly] for generic array operations *)
external[@layout_poly] get : ('a : any). 'a array -> int -> 'a = "%array_safe_get"

(* Define a template with layout parameter *)
let%template[@kind k = (value, bits64, value & bits64 & bits64)] identity
  (type a : k)
  (x : a)
  = x

(* Use with explicit layout annotation *)
let id_int = (identity [@kind value]) 42
let id_float = (identity [@kind bits64]) #3.14

(* Template module type - generates versions for each layout *)
module type%template [@kind k = (value, value & bits64 & bits64)] Stringy = sig
  type t : k
  val length : t -> int64#
  val get : t -> int64# -> char
end

(* Use in function with matching layout annotation *)
let%template[@kind k = (value, value & bits64 & bits64)] process
  (type s : k)
  (module S : Stringy with type t = s[@kind k])
  (input : s)
  = S.length input

(* Call with specific layout *)
let len = (process [@kind value]) (module String) "hello"
let len = (process [@kind value & bits64 & bits64]) (module Slice) slice

(* Prefer unboxed types (with #) - they live in XMM/YMM registers *)
(* 128-bit: int8x16#, int16x8#, int32x4#, int64x2#, float32x4#, float64x2# *)
(* 256-bit: int8x32#, int16x16#, int32x8#, int64x4#, float32x8#, float64x4# *)

(* Boxed types (without #) exist for when you need them in boxed containers *)
(* e.g., int8x16 option, int8x16 list - but prefer unboxed where possible *)

open Ocaml_simd_sse  (* or Ocaml_simd_neon for Arm *)

(* Intrinsics operate on unboxed types *)
let v : float32x4# = Float32x4.set 1.0 2.0 3.0 4.0
let v : float32x4# = Float32x4.sqrt v

(* Load from strings/bytes/arrays *)
let vec : int8x16# = Int8x16.String.get text ~byte:0

(* Compile-time constants with ppx_simd *)
let z : int32x4# = Int32x4.blend [%blend 0, 1, 0, 1] x y

(* Store in arrays efficiently *)
let arr : int8x16# array = [| vec |]

open Iarray.O

let arr : string iarray = [: "zero"; "one"; "two" :]
let first = arr.:(0)              (* projection with .: *)

(* Covariant: sub iarray :> super iarray when sub :> super *)
(* Can be stack-allocated via Iarray.Local *)

let result = ~sum:0, ~product:1
let (~sum, ~product) = result     (* pattern matching with punning *)

(* Type: sum:int * product:int *)

(* Partial/reordered patterns when type is known *)
let ~y, .. = lt                   (* extract just y *)

(* Partial labeling *)
type t = min:int * max:int * float

let triangle n =
  let mutable total = 0 in
  for i = 1 to n do
    total <- total + i
  done;
  total

let[@zero_alloc] add x y = x + y              (* checked *)
let[@zero_alloc strict] f x = ...             (* strict: no allocs even on exception paths *)
let[@zero_alloc opt] f x = ...                (* only checked in optimized builds *)
let[@zero_alloc assume] log_error msg = ...   (* trusted, not checked *)

(* In signatures *)
val[@zero_alloc] f : int -> int

(* Module-wide *)
[@@@zero_alloc all]
let[@zero_alloc ignore] make x y = (x,y)      (* opt-out *)

(* Fork/join - arguments must be portable *)
let a, b = Parallel.fork_join2 par
  (fun _par -> compute_a ())
  (fun _par -> compute_b ())

(* Parallel sequences *)
let seq = Parallel.Sequence.of_iarray arr
let sum = Parallel.Sequence.reduce par seq ~f:(+)

(* Atomics for shared mutable state *)
let counter = Atomic.make 0
let _ = Atomic.fetch_and_add counter 1

(* Capsules for protected mutable state *)
let data = Capsule.Data.create (fun () -> ref 0)
let mutex = Capsule.Mutex.create ()

(* immutable_data: no functions/mutable fields, crosses portability+contention *)
(* mutable_data: no functions, crosses portability *)
(* value: standard OCaml, crosses nothing *)

type t : immutable_data    (* kind annotation *)

open Unboxed

let[@zero_alloc] sum_floats (data : float# array) =
  let mutable acc = #0.0 in
  for i = 0 to Array.length data - 1 do
    acc <- F64.O.(acc + data.(i))
  done;
  acc

let[@zero_alloc] sum_int64s (data : int64# array) =
  let mutable acc = #0L in
  for i = 0 to Array.length data - 1 do
    acc <- I64.O.(acc + data.(i))
  done;
  acc

open Unboxed

let count_with_ref () =
  let counter = I64.Ref.create #0L in
  for i = 1 to 100 do
    I64.Ref.set counter I64.O.(I64.Ref.get counter + I64.of_int i)
  done;
  I64.Ref.get counter

open Unboxed

(* Use UFO for optional float results without allocation *)
let[@zero_alloc] safe_divide x y =
  if F64.O.(y = #0.0) then UFO.none ()
  else UFO.some F64.O.(x / y)

(* Pattern match with match%optional_u - specify module path inline *)
let[@zero_alloc] apply_or_default opt ~f ~default =
  match%optional_u.Packed_float_option.Unboxed opt with
  | None -> default
  | Some x -> f x

let result = safe_divide #10.0 #2.0  (* UFO with #5.0 *)
let doubled = apply_or_default result ~f:(fun x -> F64.O.(x * #2.0)) ~default:#0.0

let parallel_map par arr ~f =
  let seq = Parallel.Sequence.of_iarray arr in
  Parallel.Sequence.map par seq ~f
  |> Parallel.Sequence.to_iarray

let with_temp_buffer ~f =
  let buf = stack_ (Bytes.create 1024) in
  f (buf @ local)