mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-18 16:32:11 +01:00
Add doc/note/memory-safety.md
This commit is contained in:
1 parent
61c463273b
commit
1536b3b6ba
1 file changed
+68
@@ -0,0 +1,68 @@
|
||||
# Memory-Safety
|
||||
|
||||
Wuffs is a memory-safe programming language, with compiler-enforced [bounds
|
||||
checking](/doc/note/bounds-checking.md) against buffer overflows and `nullptr`
|
||||
dereferences. By default, it also prevents uninitialized reads, although some
|
||||
[zero-initialization is
|
||||
optional](/doc/note/initialization.md#partial-zero-initialization), for
|
||||
additional performance.
|
||||
|
||||
A deliberate constraint in the Wuffs language is that struct fields cannot
|
||||
store any pointers to dynamically allocated memory, only to e.g. statically
|
||||
allocated error messages (a `base.status`). When a Wuffs decompressor reads
|
||||
from or writes to a buffer, that buffer has to be passed on every call, instead
|
||||
of e.g. being passed once during initialization and saved to a field. There is
|
||||
no ambiguity about whether the caller or callee owns some memory, even when
|
||||
encountering an error. It's always caller-owned and callee-borrowed.
|
||||
|
||||
Wuffs is also trivially safe against things like memory leaks, use-after-frees
|
||||
and double-frees because Wuffs code doesn't even have the *capability* to
|
||||
allocate or free memory. Wuffs is certainly less powerful than other
|
||||
programming languages, but with less power comes easier proof-of-safety. Still,
|
||||
Wuffs is not a toy language and can do [real work](/example).
|
||||
|
||||
Wuffs is a language for writing libraries, and complete programs require
|
||||
combining Wuffs with another programming language. The obvious example is the
|
||||
C/C++ programming language, but it could be something else. For argument's
|
||||
sake, let's call it "PL".
|
||||
|
||||
If "PL" is not memory-safe, then clearly "Wuffs + PL" is also not memory-safe
|
||||
overall. Nonetheless, "Wuffs + PL" is still safer than "just PL", especially if
|
||||
the Wuffs parts are the only ones that are in direct contact with untrusted
|
||||
(and possibly maliciously crafted) inputs. There is value in structuring a
|
||||
program so that the bulk of the computation happens in Wuffs (memory-safe even
|
||||
for performant, relatively complicated code) and the memory-unsafe
|
||||
configuration, outside of inner loops, can be in relatively simple code that
|
||||
prioritizes readability over raw performance.
|
||||
|
||||
|
||||
## Allocation-Free APIs
|
||||
|
||||
The inability for Wuffs libraries to allocate memory means that their APIs may
|
||||
look unfamiliar at first. For example, there isn't a single "decode a JPEG"
|
||||
function. Instead, [image decoding](/doc/std/image-decoders.md) typically
|
||||
involves multiple steps:
|
||||
|
||||
1. Call into Wuffs with the compressed image input to discover the image
|
||||
configuration: its width, height, color model, etc. Only some of the input
|
||||
will be consumed.
|
||||
2. The caller then allocates a sufficiently large pixel buffer for that
|
||||
configuration or otherwise issues a "too large to decode" error.
|
||||
3. Call into Wuffs again, passing that pixel buffer and the remaining input.
|
||||
|
||||
For [compression decoding](/doc/std/compression-decoders.md), a fixed size
|
||||
buffer can be re-used, combining [I/O buffers](/doc/note/io-input-output.md)
|
||||
with [coroutines](/doc/note/coroutines.md). The
|
||||
[example/zcat](/example/zcat/zcat.c) program can decompress arbitrarily large
|
||||
input using static buffers, without ever calling `malloc`. Indeed, on Linux,
|
||||
that program self-imposes a `SECCOMP_MODE_STRICT` sandbox, prohibiting dynamic
|
||||
memory allocation (amongst many other useful but dangerous things) at the
|
||||
kernel level.
|
||||
|
||||
|
||||
## Thread-Safety
|
||||
|
||||
Unless otherwise noted, a Wuffs object is not thread-safe, but Wuffs code also
|
||||
lacks the capability to create, destroy or otherwise manage threads. There is
|
||||
also no global mutable state, so two separate Wuffs objects are safe to use
|
||||
from two separate threads.
|
||||
Reference in new issue
Block a user