channels: initial content

shayne-fletcher · facebook-github-bot · commit a31ce6a9498f · 2025-08-21T15:08:34.000-07:00
Summary: adds channels section to the book toc and stubs out pages (index, tx_rx, addresses, transports, frames). updates readme and introduction to reference channels.

Reviewed By: colin2328

Differential Revision: D80594232

fbshipit-source-id: c0d4e61b818e72478d9eda4d875c4be88408660e
diff --git a/docs/source/books/hyperactor-book/README.md b/docs/source/books/hyperactor-book/README.md
@@ -8,8 +8,9 @@ This is the development documentation for the hyperactor system, built using [`m
 
 ./src/introduction
 ./src/refrences
-mailbox
 macros
+mailbox
+channels
 actors
 summary
 ```
diff --git a/docs/source/books/hyperactor-book/src/SUMMARY.md b/docs/source/books/hyperactor-book/src/SUMMARY.md
@@ -20,6 +20,11 @@
   - [Delivery Semantics](mailboxes/delivery.md)
   - [Multiplexers](mailboxes/multiplexer.md)
   - [Routers](mailboxes/routers.md)
+- [Channels](channels/index.md)
+  - [Transmits and Receives](channels/tx_rx.md)
+  - [Channel Addresses](channels/addresses.md)
+  - [Transports](channels/transports.md)
+  - [Frames](channels/frames.md)
 - [Actors](actors/index.md)
   - [Actor](actors/actor.md)
   - [Handler](actors/handler.md)
diff --git a/docs/source/books/hyperactor-book/src/channels/addresses.md b/docs/source/books/hyperactor-book/src/channels/addresses.md
@@ -0,0 +1,3 @@
+# Channel Addresses
+
+Channel addresses (`ChannelAddr`) identify endpoints and encode transport type (tcp, unix, local, sim, etc.).
diff --git a/docs/source/books/hyperactor-book/src/channels/frames.md b/docs/source/books/hyperactor-book/src/channels/frames.md
@@ -0,0 +1,3 @@
+# Frames
+
+Frames define the wire format. A length-prefixed protocol carries serialized messages and acknowledgements. `FrameReader` and `FrameWrite` ensure cancellation safety.
diff --git a/docs/source/books/hyperactor-book/src/channels/index.md b/docs/source/books/hyperactor-book/src/channels/index.md
@@ -0,0 +1,3 @@
+# Channels
+
+Channels provide one-way, typed message passing between processes. They abstract over multiple transports while offering a uniform Tx/Rx API.
diff --git a/docs/source/books/hyperactor-book/src/channels/transports.md b/docs/source/books/hyperactor-book/src/channels/transports.md
@@ -0,0 +1,3 @@
+# Transports
+
+Different transports implement the channel abstraction: Local (in-process), Tcp, Unix, MetaTls, and Simulated.
diff --git a/docs/source/books/hyperactor-book/src/channels/tx_rx.md b/docs/source/books/hyperactor-book/src/channels/tx_rx.md
@@ -0,0 +1,3 @@
+# Transmits and Receives
+
+Transmit (`Tx`) and receive (`Rx`) ends define the basic channel interface. `Tx` can post or send messages, `Rx` can asynchronously receive them.
diff --git a/docs/source/books/hyperactor-book/src/introduction.md b/docs/source/books/hyperactor-book/src/introduction.md
@@ -12,8 +12,8 @@ We hope this becomes the book we wish we had when we started working with Monarc
 
 ./actors/index
 ./macros/index
+./channels/index
 ./mailboxes/index
 ./references/index
 ./SUMMARY.md
-
 ```

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Channel Addresses`
	`2`	`+`
	`3`	+Channel addresses (`ChannelAddr`) identify endpoints and encode transport type (tcp, unix, local, sim, etc.).
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Frames`
	`2`	`+`
	`3`	+Frames define the wire format. A length-prefixed protocol carries serialized messages and acknowledgements. `FrameReader` and `FrameWrite` ensure cancellation safety.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Channels`
	`2`	`+`
	`3`	`+Channels provide one-way, typed message passing between processes. They abstract over multiple transports while offering a uniform Tx/Rx API.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Transports`
	`2`	`+`
	`3`	`+Different transports implement the channel abstraction: Local (in-process), Tcp, Unix, MetaTls, and Simulated.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Transmits and Receives`
	`2`	`+`
	`3`	+Transmit (`Tx`) and receive (`Rx`) ends define the basic channel interface. `Tx` can post or send messages, `Rx` can asynchronously receive them.