unikernel/duniverse/optint/README.md

@@ -0,0 +1,40 @@
+Optint - Efficient integer types on 64-bit architectures
+========================================================
+
+This library provides two new integer types, `Optint.t` and `Int63.t`, which
+guarantee efficient representation on 64-bit architectures and provide a
+best-effort boxed representation on 32-bit architectures.
+
+## Goal
+
+The standard `Int32.t` and `Int64.t` types provided by the standard library have
+the same heap-allocated representation on all architectures. This consistent
+representation has costs in both memory and run-time performance.
+
+On 64-bit architectures, it's often more efficient to use the native `int`
+directly.
+This library provides types to do exactly this: 
+
+- `Optint.t`: an integer containing _at least_ 32 bits. On 64-bit, this is an
+  immediate integer; on 32-bit, it is a boxed 32-bit value. The overflow
+  behaviour is platform-dependent.
+
+- `Int63.t`: an integer containing _exactly_ 63 bits. On 64-bit, this is an
+  immediate integer; on 32-bit, it is a boxed 64-bit integer that is wrapped to
+  provide 63-bit two's complement semantics. The two implementations are
+  observationally equivalent, modulo use of `Marshal` and `Obj`.
+
+In summary:
+
+| Integer type         | 32-bit representation  | 64-bit representation  | Semantics          |
+| --                   | --                  | --                  | --                 |
+| `Stdlib.Int.t`       | 31-bit immediate ✅ | 63-bit immediate ✅ | Always immediate   |
+| `Stdlib.Nativeint.t` | 32-bit boxed ❌     | 64-bit boxed ❌     | Exactly word size  |
+| `Stdlib.Int32.t`     | 32-bit boxed ❌     | 32-bit boxed ❌     | Exactly 32 bits    |
+| `Stdlib.Int64.t`     | 64-bit boxed ❌     | 64-bit boxed ❌     | Exactly 64 bits    |
+| `Optint.t` (_new_)   | 32-bit boxed ❌     | 63-bit immediate ✅ | _At least_ 32 bits |
+| `Int63.t` (_new_)    | 64-bit boxed ❌     | 63-bit immediate ✅ | Exactly 63 bits    |
+
+These new types are safe and well-tested, but their architecture-dependent
+implementation makes them unsuitable for use with the `Marshal` module. Use the
+provided encode and decode functions instead.