Document Pool's unusual requirements.

Author: jimblandy

wgpu-remote/src/pool/mod.rs

@@ -1,13 +1,28 @@
 /*! A heap allocator for shared memory blocks.
 
-This module defines the [`Pool`] type, which suballocates blocks from some
-large underlying contiguous block of memory. This crate uses a [`Sender`]
-implementation to create large blocks of memory shared between client and server,
-and then uses [`Pool`] to dice those large blocks up into individual buffers
-for mapping wgpu [`Buffer`]s, large buffer writes, and so on.
-
-This allocator uses the [Binary Buddy][bb] algorithm to place allocated blocks
-and coalesce free ranges.
+This module defines the [`Pool`] type, which suballocates blocks from
+some large underlying contiguous block of memory. It uses the [Binary
+Buddy][bb] algorithm to place allocated blocks and coalesce free
+ranges.
+
+This crate uses a [`Sender`] implementation to create large blocks of
+memory shared between client and server, and then uses [`Pool`] to
+subdivide those large blocks up into individual buffers for mapping
+wgpu [`Buffer`]s, large buffer writes, and so on.
+
+## Why do we need another allocator?
+
+There are plenty of heap allocators out there, but this crate has the
+unusual constraint that the memory being managed may be writable by an
+untrusted party. This means that we can't use free space to hold
+memory management metadata like freelists, page headers, and so on.
+All our metadata must live outside the underlying blocks of shared
+memory.
+
+One nice consequence of keeping the metadata separate is that the
+allocator uses only one piece of unsafe code, for constructing the
+sub-`Block` of the larger block we're dicing up. The rest of this
+allocator simply operates on ordinary safe Rust types.
 
 [`Sender`]: crate::transport::Sender
 [`Buffer`]: https://docs.rs/wgpu/latest/wgpu/struct.Buffer.html