40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
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.
|