From b71df58f2fb4ed85d4c8cf806d5837ce63c73f31 Mon Sep 17 00:00:00 2001
From: Emil Fresk <emil.fresk@gmail.com>
Date: Wed, 22 Sep 2021 13:22:45 +0200
Subject: The great docs update

---
 book/en/src/by-example/tips_indirection.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 book/en/src/by-example/tips_indirection.md

(limited to 'book/en/src/by-example/tips_indirection.md')

diff --git a/book/en/src/by-example/tips_indirection.md b/book/en/src/by-example/tips_indirection.md
new file mode 100644
index 0000000..22c5774
--- /dev/null
+++ b/book/en/src/by-example/tips_indirection.md
@@ -0,0 +1,26 @@
+# Using indirection for faster message passing
+
+Message passing always involves copying the payload from the sender into a
+static variable and then from the static variable into the receiver. Thus
+sending a large buffer, like a `[u8; 128]`, as a message involves two expensive
+`memcpy`s. To minimize the message passing overhead one can use indirection:
+instead of sending the buffer by value, one can send an owning pointer into the
+buffer.
+
+One can use a global allocator to achieve indirection (`alloc::Box`,
+`alloc::Rc`, etc.), which requires using the nightly channel as of Rust v1.37.0,
+or one can use a statically allocated memory pool like [`heapless::Pool`].
+
+[`heapless::Pool`]: https://docs.rs/heapless/0.5.0/heapless/pool/index.html
+
+Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
+
+``` rust
+{{#include ../../../../examples/pool.rs}}
+```
+
+``` console
+$ cargo run --target thumbv7m-none-eabi --example pool
+{{#include ../../../../ci/expected/pool.run}}
+```
+
-- 
cgit v1.2.3